
#############################################################################
# Ipswitch Mailing List Readme File
# Copyright (C) 1999 Ipswitch, Inc.
#
# Ipswitch Inc, grants any valid licensee of IMail for Windows NT the right
# to modify this source and use the modified version of software generated
# from the source with any implementation of IMail for Windows NT.
# 
# NOTE: The information in this file is for experienced Perl developers 
# to use to extend the capabilities of IMail Server.  It is beyond 
# the scope of this document and Ipswitch technical support to provide any 
# guidance on writing Perl scripts.
# 
#############################################################################

====WHAT YOU NEED====

Included are the files you will need to set up your mailing list via web form.
The file, imailcgi.exe, is a command line emailer that is used by the perl
script and must be installed on your web server. The perl script also uses
the perl5 module, cgi.pm, for parsing and interpreting query strings. You
can download this module at www.perl.com (it comes with the latest
version of ActivePerl). 

To install imailcgi.exe
1. Copy imailcgi to your "\WINNT\SYSTEM32" directory, or to any other
directory in your path
2. Run "imailcgi -install yourhost.domain.top-level-domain (e.g imail.ipswitch.com) youruserid@domain (e.g. user@ipswitch.com)"

====DIRECTORY STRUCTURE====

The files included must be in the following directory structure for the scripts to work. If you choose to use a different directory structure, then you must edit the scripts.

------------

<root web> (e.g. wwwroot)

html_files (this folder can be named anything you want e.g "mailing_lists")
    mailing-lists.html
    mailing-lists_conf.html

cgi (this folder holds the perl script and must be named cgi)
    imailsrv2.pl
------------

System32 (this folder is in your WINNT directory and is where you installed imailcgi.exe. NOTE: If you installed imailcgi.exe in a different directory, then all the files below should be placed in that directory instead.)
    imailcgi.exe
    nochange.txt
    suberror.txt

------------

Imail (this is the directory where IMail was installed (probably c:\Imail) You will need to create a program alias that points to the file below - see CREATING A PROGRAM ALIAS)
    subscribe1.pl


====CUSTOMIZING YOUR FILES====

You will need to customize several of the files in order for them to work with your list server. Before editing the files, make sure you know the following information:

1. List Server Address: listserv@yourhost.domain.top-level-domain (e.g imailsrv@list.ipswitch.com)

2. The Names of each of your Discussion Lists (e.g. IMail_Forum, WSFTP_Forum)

3. The full URL to the confirmation page - mailing-lists_conf.html (e.g. http://www.ipswitch.com/html_files/mailing-lists_conf.html)

4. The full path to your temp directory - with no trailing backslash (usually c:\temp)

5. Program Alias Address: program_alias@yourhost.domain.top-level-domain (e.g. subscribe@list.ipswitch.com) see CREATING A PROGRAM ALIAS for more details...

----------
Customizing mailing-lists.html:
1. Open mailing-lists.html in a text editor and look for the line <!-- replace the hidden values below -->. Replace each hidden field with its correct value. NOTE: Discussion List names must be in a comma delimited list. The Subject value is the text that you want the user to see in the subject line of the e-mail they are sent when they subscribe (e.g. Discussion List Request).
2. Replace the name value of each drop down box with its correct value (if you have less than or greater than 3 discussion lists, you will need to add or delete drop down boxes as necessary).
----------
Customizing mailing-lists_conf.html:
This is the html page users will see after subscribing/unsubscribing from a list - you can customize it to say anything you want.
----------
Customizing subscribe1.pl:
This is the perl script that is called by your program alias when someone replies to a subscribe/unsubscribe e-mail.
1. Open subscribe1.pl in a text editor and look for the line ######### STEP 1 - ENTER YOUR PROGRAM ALIAS ##########.
Replace program_alias@yourhost.domain.top-level-domain with your program alias address. Do the same for steps 2, 4 and 5*.
2. Search for the line ######### STEP 3 - ENTER THE PATH TO YOUR TEMP DIRECTORY ##########. Replace the words Full Path To Temp Directory with your temp directory path. NOTE: YOU MUST USE DOUBLE BACKSLASHES AND THERE SHOULD BE NO TRAILING BACKSLASH (e.g. c:\\temp).
3. Search for the line ######### STEP 6 - ENTER YOUR LIST SERVER ADDRESS ##########. Replace listserv@yourhost.domain.top-level-domain with your List Server Address*.

*IMPORTANT: When adding any list server or program alias addresses to subscribe1.pl, you must use an escape character (\) before the "@" symbol or Perl will not interpret this character correctly. For example, imailsrv@list.ipswitch.com should be written imailsrv\@list.ipswitch.com.
----------
Customizing nochange.txt and suberror.txt
These files contain text that is e-mailed to the user if an error occurs - you can customize them to say whatever you want.


====CREATING A PROGRAM ALIAS====
You can use the IMail Administrator to create a program alias which points to a program (in this case subscribe1.pl) that can accept the mail message for further processing. 

1. Open the IMail Administrator.
2. Expand the Virtual Domains List and select the domain to which you want to add an alias.
3. Click the Add Alias button and enter a name for the alias (e.g. subscribe).
4. Click the Next button and select "Program" as the alias type.
5. Click the Next button and enter the paths to your perl application and to the program itself (e.g. c:\Perl\bin\perl.exe c:\imail\subscribe1.pl). 





