mail-merge-help/README

   1 Using the "mail-merge" script
   2 =============================
   3
   4 The mail-merge script (if this file is ./mail-merge-help/README, it should be
   5 ./mail-merge) is a simple tool for combining a CSV file of data with a Python
   6 template for an email, and sending it out.
   7
   8 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.
   9
  10 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.
  11
  12 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.
  13
  14 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.
  15
  16 Sample files are also available in this directory.
  17
  18 Putting these all together, you'll probably want a command like:
  19 add adehnert        # If on an Athena machine, to make the script available
  20 cd /mit/adehnert/Public/software/my-snippets/mail-merge-help                # change to the directory with your data files
  21 mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.test.csv # repeat until the message looks good
  22 mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.csv      # run just once
  23
  24 The script will output the rows in the CSV file, as it parsed them, as it reads and processes them.
  25
  26 The mail-merge command should work on any Athena machine (and most other machines with Python installed).
  27
  28 Please feel free to contact me (adehnert@mit.edu) with any questions.
  29
  30
  31 Using mail-merge with RT
  32 ------------------------
  33
  34 mail-merge now supports limited RT interaction. To use with RT, you should:
  35
  36 * Use the --rt-queue option, passing the queue name (if it contains no spaces)
  37   or ID number (which can be found on https://help.mit.edu/Admin/Queues/)
  38
  39 * Make sure to put the queue correspondence address (eg,
  40   asa-exec-correspondence@mit.edu) as the cc_addr (first argument)
  41
  42 * Optionally, pass --rt-owner, to set the Owner and add them as an AdminCC on
  43   the created tickets
  44
  45 mail-merge will automatically create the ticket, set the value of the "email"
  46 field as Requestor, and email the correspondence address (not the "email" value
  47 directly) with your ticket.