MailMerge


   This program is a very simple mail merge system
and SMTP client.  Using the simple graphical user
interface, you can send a form letter to a specified
set of e-mail addresses, filling in fields in the
letter.  There are a lot of missing features, but in
general the program is sufficiently functional to 
be used for modest mailings.

   To use the program, you must do four things:
first, find a mail server, second, select an
e-mail address you want the letters to appear to
come from, third, set up a template, and fourth,
set up a data file.  

   If you need to recompile the program, simply
invoke your Java compiler on all four .java source
files:

		   > javac -g *.java

   To run the program, simply invoke it with your
Java runtime.  Assuming that Java is on your PATH,
and that you've installed the mailmerge classes in
a directory named mailmerge, here is how you could
run the program:

                   > cd mailmerge
   	      THEN
                   > javaw -jar mailmerge.jar
                OR
		   > java MergeGui


   The topics below describe the setup steps in
more detail.

1. Find a Mail Server

   Usually, your internet service provider will
inform you of what mail server to use.  You would
normally have configured this in your e-mail
tool.  

2. Select a Sender E-mail Address

   Usually, you can just use your own address.
If you are sending out messages on behalf of 
somebody else, then use their address.  Note that
some e-mail servers will discard letters that do
not have a proper sender address.

3. Setting up a Template

   To use the program, you must create a form letter
template.  The template looks just like the body of
an RFC-822 message, but with substitution fields in it.
The substitution fields have this form:   $N  where N
is an interger 0 or greater.  During mail processing,
each field will be replaced by the values from the
data file (see below).  Here is an example template:

           Date: 23 Mar 2000 16:00:00
	   Content-type: text/plain
	   
	   Dear $1,

	   This is to inform you that the next
	   corporate meeting will be held April 4.
	   For more information, contact your
	   division coordinator, $2 on ext. $3.

	   Sincerely, 
		      Jim Smith, Meeting Manager
		      jsmith@bigcorp.com


So, this template uses three fields: $1, $2, and $3.
Field $0 is reserved and is always the recipient's
e-mail address.


4. Setting up a Data File

    A mail merge data file specifies the recipients
and field values for the form letter.  Each line in
the data file specifies one recipient.  Blank lines
and comment lines are ignored; comments start with #.
Each recipient line consists of 1 or more fields,
separated by the vertical bar character |.  Field 
values may be any string, but may not contain | or 
newline.  The first field (field 0) on each line
must be the recipient's e-mail address.

Here is an example data file:

    # mailing list for meeting attendees
    # Fields are: 
    # address|first name|coordinator|coordinator ext
    fjones@hr.bigcorp.com|Fred|Sally Forth|1491
    atyler@sales.bigcorp.com|Anne|Sam Smith|9082
    jsmith@legal.bigcorp.com|James|Will Ngo|3274|Sunday

Note that extra fields may appear, but might be
ignored if they are not used in the template.
If a template specifies a field that the data file
does not supply, then a value of an empty string
is used instead.


This program is copyright (c) Neal Ziring, 2000.
Permission to copy, reproduce, modify, and distribute
this program is granted so long as authorship credit
is preserved.  For more information, contact Neal
Ziring, ziring@home.com.
