Instructions for using mail-merge

diff --git a/mail-merge-help/README b/mail-merge-help/README
new file mode 100644 (file)
index 0000000..118defb
--- /dev/null
+++ b/mail-merge-help/README
@@ -0,0 +1,26 @@
+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
+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.

diff --git a/mail-merge-help/missing-whatever.test.csv b/mail-merge-help/missing-whatever.test.csv
new file mode 100644 (file)
index 0000000..27499b9
--- /dev/null
+++ b/mail-merge-help/missing-whatever.test.csv
@@ -0,0 +1,2 @@
+"email","FNAME","LNAME",group_id
+"adehnert@mit.edu","Alex","Dehnert",1955

diff --git a/mail-merge-help/missing-whatever.txt b/mail-merge-help/missing-whatever.txt
new file mode 100644 (file)
index 0000000..a8bf8c5
--- /dev/null
+++ b/mail-merge-help/missing-whatever.txt
@@ -0,0 +1,11 @@
+To: %(FNAME)s %(LNAME)s <%(email)s>
+Subject: Missing whatever for %(FNAME)s %(LNAME)s
+From: asa-exec@mit.edu
+CC: asa-exec@mit.edu
+
+Hello %(FNAME)s %(LNAME)s,
+
+You have not yet filled out the whatever form. You are required to do this before 1/1/1970. You can do so at https://asa.mit.edu/whatever/%(group_id)s.
+
+Thanks,
+ASA Exec