Using the "mail-merge" script
=============================

The mail-merge script (if this file is ./mail-merge-help/README, it should be
./mail-merge) is a simple tool for combining a CSV file of data with a Python
template for an email, and sending it out.

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.

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.

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.

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.

Sample files are also available in this directory.

Putting these all together, you'll probably want a command like:
add adehnert        # If on an Athena machine, to make the script available
cd /mit/adehnert/Public/software/my-snippets/mail-merge-help                # change to the directory with your data files
mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.test.csv # repeat until the message looks good
mail-merge asa-admin@mit.edu missing-whatever.txt missing-whatever.csv      # run just once

The script will output the rows in the CSV file, as it parsed them, as it reads and processes them.

The mail-merge command should work on any Athena machine (and most other machines with Python installed).

Please feel free to contact me (adehnert@mit.edu) with any questions.


Using mail-merge with RT
------------------------

mail-merge now supports limited RT interaction.


One-time set-up
~~~~~~~~~~~~~~~

To do this, mail-merge needs to know your RT username and password. It
automatically read it from the same `~/.rtrc` that the command-line RT client
will use. You should create a file called .rtrc in your home directory
containing:

"""
server https://help.mit.edu/
user your-username
passwd your-password
query ( Status='new' or Status='open' or Status='stalled' )
"""

If you don't have a password for RT (separate from your Athena password), you
can set one at https://help.mit.edu/User/Prefs.html.

Usage
~~~~~

To use RT for a given mail-merge operation, you should:

* Use the --rt-queue option, passing the queue name (if it contains no spaces)
  or ID number (which can be found on https://help.mit.edu/Admin/Queues/)

* Make sure to put the queue correspondence address (eg,
  asa-exec-correspondence@mit.edu) as the cc_addr (first argument)

* Optionally, pass --rt-owner, to set the Owner and add them as an AdminCC on
  the created tickets

An example commandline is:
mail-merge --rt-queue=ASA::Database asa-db-correspondence@mit.edu missing-whatever.txt missing-whatever.test.csv

(Replace ASA::Database with your queue name (or number; note that if your queue
name contains a space, it must be the number), and
asa-db-correspondence@mit.edu with your queue correspondence address.)

mail-merge will automatically create the ticket, set the value of the "email"
field as Requestor, and email the correspondence address (not the "email" value
directly) with your ticket.