Document the process for sending emails

README.md

@@ -19,6 +19,41 @@ The markdown should be rendered to HTML before sending; the VSCode markdown prev
 
 ## How to send emails
 
+### Within a competition cycle
+
+During a competition cycle the emails can be sent in one of two ways.
+Since we offer teams the option of having their secondary contact(s) CCd into emails, we are unable to use GMail's mail merge feature.
+
+For either of these routes you will need to have configured your SR GMail account to be able to send from `teams@`.
+
+#### Personalised emails
+
+1. Set up a Python virtual environment and `pip install -r scripts/requirements.txt`
+1. Export as a CSV the "Combined" tab of the current year's "Teams Organisation (internal)" spreadsheet
+1. Pre-process that file using `./scripts/process-export.py $EXPORTED.csv > $EXPORTED.processed.csv`
+1. Send the email using `./scripts/send.py`:
+    1. Create a fresh "app password" for your account for use by the script; set that via ` export SMTP_PASSWORD=...`
+    1. Set your username via `export SMTP_USERNAME=...`
+    1. Dry-run the send via the `--dry-run`, check that the printed output is what you expect
+    1. You may also want to dummy send the email to yourself; this requires creating a dummy CSV with equivalent columns to the processed file and then sending the email. Be sure you're sending to the right file when doing this!
+    1. Send the actual email. For 30 teams this takes a couple of minutes as the script rate-limits itself to avoid hitting GMail sending limits.
+    1. Delete from your account the app password you created in the earlier step
+
+#### Mailshots
+
+When no personalisation is needed, the email can be sent as a mailshot.
+This involves:
+
+* Rendering the email markdown yourself (VSCode's preview tab does this well for example)
+* Identifying the recipient email addresses yourself (don't forget to include the secondary contacts for teams requesting that)
+* Composing the email in your own SR GMail account
+* Setting the email to be sent from `teams@`
+* Setting the email as `To` `teams@`
+* Putting all the recipient emails in the `BCC` field
+* Copy/pasting the rendered email body into the email
+
+### Outside a competition cycle
+
 Emails should be sent using the MailChimp account.
 
 When sending emails to 'All Teams', please send to both the _"Website - Potential Team Leaders"_ and _"Potential Team Leaders"_ lists.

scripts/process-export.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+
+"""
+Script for processing an exported CSV from the "Combined" tab of the current
+year's "Teams Organisation (internal)" spreadsheet for use in emailing teams.
+
+Outputs to standard output, typical usage is to redirect that to a file.
+"""
+
+import argparse
+import csv
+import re
+import sys
+from typing import TextIO
+
+
+def pascal_case(text: str) -> str:
+    if text.isupper():
+        return text
+    return re.sub(r'\W+', '', text.title())
+
+
+def main(input_csv: TextIO, in_place: bool) -> None:
+    rows = list(csv.reader(input_csv))
+
+    super_header_row = rows.pop(0)
+    header_row = rows.pop(0)
+
+    try:
+        supervisor_offset = super_header_row.index('Supervisor')
+        secondary_contact_offset = super_header_row.index('Secondary Contact')
+        secondary_contact_end = super_header_row.index('Kit Info')
+    except ValueError as e:
+        raise ValueError(f"Badly formed input file: {e}") from e
+
+    status_col = header_row.index('Status')
+
+    # Update in place to ensure the new values are written back
+    header_row = [pascal_case(x) for x in header_row]
+
+    for idx, value in enumerate(header_row):
+        if idx < supervisor_offset or idx > secondary_contact_end:
+            continue
+        if idx < secondary_contact_offset:
+            header_row[idx] = 'Primary' + value
+        else:
+            header_row[idx] = 'Secondary' + value
+
+    rows = [x for x in rows if x[status_col] not in ('Dropped Out', '')]
+
+    if in_place:
+        input_csv.seek(0)
+        input_csv.truncate()
+        output = input_csv
+    else:
+        output = sys.stdout
+
+    csv.writer(output).writerow(header_row)
+    csv.writer(output).writerows(rows)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        'input_csv',
+        help="CSV file to process",
+        type=argparse.FileType(mode='r+'),
+    )
+    parser.add_argument(
+        '--in-place',
+        action='store_true',
+        default=False,
+        help="Update the file in place (discouraged)",
+    )
+    return parser.parse_args()
+
+
+if __name__ == '__main__':
+    main(**(parse_args().__dict__))

scripts/send.py

@@ -1,3 +1,14 @@
+#!/usr/bin/env python3
+
+"""
+Script for sending emails to teams.
+
+This supports:
+ - rendering the markdown to HTML
+ - CCing secondary contacts where asked
+ - personalising the email content based on Python format string style placeholders
+"""
+
 import argparse
 import csv
 import dataclasses
@@ -129,7 +140,10 @@ def main(args: argparse.Namespace) -> None:
 
 
 def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser()
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
     parser.add_argument('template', type=Path)
     parser.add_argument('teams_csv', type=Path)
     parser.add_argument(