Documentation for emailmerge

This sends off a 'fairly fixed' piece of email to a large number of people. It's like a 'mailmerge' application, however, it's focused on email.

Usage:

  emailmerge --subject=string
             --body=filename
             --custom=filename
             [--html]
             [--dryrun]
             [--nosig]

You have to (mandatorily) supply a subject string, a body filename, and a filename of customisations (which are applied in mass production of personalised email).

Here's a sample of the body file:

  -------------------------------------------------- snip snip
  Hello, PERSON. It was fun meeting you today. Keep in touch.

      -me
  -------------------------------------------------- snip
  snip

And a customisations file that would go with it:

  -------------------------------------------------- snip snip
  email:PERSON
  ajayshah@igidr.ac.in:Ajay
  kirit@igidr.ac.in:Prof. Parikh
  -------------------------------------------------- snip snip

The customisations file must be colon delimited. The first line defines the layout of the file, which is one record per line. In the example above, the first line says that lines contain the variable `email' followed by the variable 'PERSON'. A column named 'email' is mandatory, the other columns can be named whatever you want. I generally use uppercase for variable names, like PERSON.

The Unix commandline for running this is:

  $ emailmerge --subject="Hello" --body=bodyfile --custom=people

The way this works is as follows. The customisations file is read in. For each line of data, substitutions are made where every variable name is replaced by the data field. A separate email is sent off to the stated address.

Optional arguments

--html

The visual formatting sometimes gets messed up when you do substitutions. In such situations, there is a need to reformat paragraphs after substitution has been done. The solution used by emailmerge is as follows. You provide a body file in HTML format, and utilise the flag --html. After substitutions are done, emailmerge puts the generated HTML file through lynx -dump to get plain text out of it. This plain text is sent off to the recipient.

Hence the role for HTML is only as a path to proper formatting after substitutions are done -- we do not stoop to the abomination of HTML email. Obviously, in this setup, emailmerge knows nothing about HTML standards etc: if lynx -dump does something nice with a HTML construct, you're welcome to use it.

--dryrun

The flag --dryrun goes through all the motions, but instead of sending off the generated email, it is just printed on screen so you can look at it and verify that things are going well.

--nosig

By default, $HOME/.signature is catted at the end of the body file. If you say --nosig, this is NOT done.

Download it

Here is a tarfile.

Bugs

The interaction between catting the .signature and --html is not nice, so when you have --html, you SHOULD say --nosig.
There is no provision for having attachments.

Dependencies

emailmerge is itself written in perl
It uses the perl module Getopt::Long
It uses lynx to convert HTML into plain text if --html is used
It uses "mail" to push out mail. I assume this is good old Berkeley mail, with -s for subject, etc.

Associated utility - emailmerge-palm.pl

The most basic extent of customisation is to put a salutation for each email, where you put the name of the person in. E.g. the email would start off "Dear Mr.XXX" or "Dear YYY". Here, the string "Mr.XXX" or "YYY" is called the salutation.

Users of the palm pilot can have a convention where one of the four customisation fields in the address database is used to hold the salutation. As shipped, emailmerge-palm.pl assumes that custom2 is the field where the user is keeping the salutation.

emailmerge-palm.pl reads an AddresssDB.pdb file, and prints out a file containing the email address and salutation, in the format required by emailmerge. It ignores records where the email address is not filled in. If the email address is there, a record is always generated. If the salutation is there, that's fine, otherwise a record is generated with the string "Salutation missing". If a record has multiple email addresses, a separate line is generated for each of those addresses.

In general, the output of emailmerge-palm.pl is not ready for use with emailmerge. The user will have to carefully look at the generated file and touch it up: the email he has in front of him needn't go out to all of them, some salutations are missing, sometimes there are multiple email addresses; these things imply that hand-editing of the generated file is called for. But it's a useful starting point.

Dependencies

emailmerge-palm.pl is itself written in perl
It uses the perl modules Palm::PDB and Palm::Address

Authors

Ajay Shah, Geetanjali Sampemane