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.
  35
  36
  37 One-time set-up
  38 ~~~~~~~~~~~~~~~
  39
  40 To do this, mail-merge needs to know your RT username and password. It
  41 automatically read it from the same `~/.rtrc` that the command-line RT client
  42 will use. You should create a file called .rtrc in your home directory
  43 containing:
  44
  45 """
  46 server https://help.mit.edu/
  47 user your-username
  48 passwd your-password
  49 query ( Status='new' or Status='open' or Status='stalled' )
  50 """
  51
  52 If you don't have a password for RT (separate from your Athena password), you
  53 can set one at https://help.mit.edu/User/Prefs.html.
  54
  55 Usage
  56 ~~~~~
  57
  58 To use RT for a given mail-merge operation, you should:
  59
  60 * Use the --rt-queue option, passing the queue name (if it contains no spaces)
  61   or ID number (which can be found on https://help.mit.edu/Admin/Queues/)
  62
  63 * Make sure to put the queue correspondence address (eg,
  64   asa-exec-correspondence@mit.edu) as the cc_addr (first argument)
  65
  66 * Optionally, pass --rt-owner, to set the Owner and add them as an AdminCC on
  67   the created tickets
  68
  69 An example commandline is:
  70 mail-merge --rt-queue=ASA::Database asa-db-correspondence@mit.edu missing-whatever.txt missing-whatever.test.csv
  71
  72 (Replace ASA::Database with your queue name (or number; note that if your queue
  73 name contains a space, it must be the number), and
  74 asa-db-correspondence@mit.edu with your queue correspondence address.)
  75
  76 mail-merge will automatically create the ticket, set the value of the "email"
  77 field as Requestor, and email the correspondence address (not the "email" value
  78 directly) with your ticket.