mail-merge-help/README

   1 Using the "mail-merge" script
   2
   3 The mail-merge script (if this file is ./mail-merge-help/README, it should be
   4 ./mail-merge) is a simple tool for combining a CSV file of data with a Python
   5 template for an email, and sending it out.
   6
   7 The first argument is an address to receive copies of all emails sent out (generally an archive address (gmail, discuss, ...) or some list of your organization (esp@, asa-admin@, etc.). This address will be BCC'd; if you want it to be visible to the recipients, make sure to mention it in your template.
   8
   9 Your template should contain full SMTP headers and be suitable for passing to Python's % operator. In particular, this usually means that it should start with To:, Subject:, etc. lines, and fields should be substituted using "%(fieldname)s". Note that the values of the To:, CC:, etc. fields in your template are independent from who actually recieves the email --- you can include a CC: of, say, asa-exec@mit.edu and pass asa-admin@mit.edu as the first argument of the script, and asa-admin@mit.edu will receive the emails, but to the recipients it will (mostly) appear that asa-exec@mit.edu did instead. This may be useful to encourage reply-all to go to the right place without actually spamming everybody on the list.
  10
  11 Your CSV should contain a header line with the names of your fields, followed by several data lines. As is (definitionally) the case with any CSV file, fields on a given line should be comma-separated. The field named "email" will be used as the recipient of the email. The rest of the fields have no defined meaning, but can be substituted into your template.
  12
  13 I recommend creating both a "test" CSV file, containing just one row with your email address, and a real CSV file. Run the mail merge script repeatedly on the test CSV file until you're happy with the template, and then run it on the real file.
  14
  15 Sample files are also available in this directory.
  16
  17 Putting these all together, you'll probably want a command like:
  18 add adehnert        # If on an Athena machine, to make the script available
  19 mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.test.csv   # repeat until the message looks good
  20 mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.csv        # run just once
  21
  22 The script will output the rows in the CSV file, as it parsed them, as it reads and processes them.
  23
  24 The mail-merge command should work on any Athena machine (and most other machines with Python installed).
  25
  26 Please feel free to contact me (adehnert@mit.edu) with any questions.