{"id":1108,"title":"SOP: Email Send Workflow","slug":"sop-email-send","html_content":"

SOP: Email Send Workflow

\n

Purpose

\n

Standard process for composing and sending branded emails to Westside parents. Used by agents (Ava, Penny, dev agents) and humans (Lucas, Marcus). Applies to all email sends — blasts, transactional, and one-off. Produces a sent email with EmailLog audit trail, or a clear \"not approved\" stop. The key outcome is that new emails can be sent without code changes when the layout and audience query already exist.

\n

Steps

\n
    \n
  1. Intake. Requester (Marcus or Lucas) describes email intent. Composer (agent) determines:\n
      \n
    1. Layout — notification (info only), action (CTA button), or announcement (multi-section). See arch-email for layout definitions.
      2. \n
    2. Audience — which query from email_queries.py registry (e.g. unsigned_contracts, incomplete_profiles). If no query exists for this audience, STOP — create a Forgejo issue + board item for the new query first.
      3. \n
    3. EmailType — which EmailType enum value. If none exists, STOP — create a Forgejo issue + board item for the migration first.
      4. \n
    \n
    2. \n
  2. Draft content. Composer writes the email data dict and presents it to Approver (Lucas) in the conversation. Include: layout, email_type, query, subject (with per-recipient {{placeholders}}), data dict (headline, body, cta_text, cta_url, footer_note). Do NOT call any endpoint yet.
    3. \n
  3. Approver reviews draft text. Approver says \"looks good\" or requests changes. If changes requested, revise and re-present. Loop until text is approved.
    4. \n
  4. Send test email. Call POST /email/blast with the draft payload plus \"test_email\": \"draneylucas@gmail.com\". Report: \"Test email sent to draneylucas@gmail.com. Check your phone.\"
    5. \n
  5. STOP — wait for approval. Do NOT proceed. Approver checks email on their phone (real Gmail renderer, real mobile viewport). Approver responds:\n
      \n
    1. \"Approved\" → proceed to Step 6.
      2. \n
    2. \"Change X\" → go back to Step 2, revise content, re-send test. Loop until approved.
      3. \n
    3. \"Kill it\" → stop entirely. Do not send.
      4. \n
    \n
    6. \n
  6. Confirm blast scope. Query the audience count: report \"Sending to N parents. Confirm?\" Wait for explicit \"send it\" or \"yes\" from Approver.
    7. \n
  7. Blast. Call POST /email/blast without test_email param. Report results: \"Sent N emails. M errors: [details if any].\"
    8. \n
  8. Verify. Confirm EmailLog entries via database query or admin endpoint. Report send count matches expected audience.
    9. \n
\n

Contract Emails (Enhanced Gate)

\n

Contract-related emails (contract_offer, contract_reminder) require double approval:

\n
    \n
  1. Steps 1-5 as above (first approval after test email on phone).
    2. \n
  2. Approver says \"approved\" after checking test on phone.
    3. \n
  3. Show recipient list and count. Approver says \"send it\" (second approval).
    4. \n
  4. Send ONE real email to a single parent (not test_email — a real recipient). Approver verifies in that parent's Gmail if possible, or confirms intent.
    5. \n
  5. Approver says \"yes, blast the rest\" (third confirmation). Then blast.
    6. \n
\n

New Email Type Checklist

\n

If the email needs infrastructure that doesn't exist:

\n
    \n
  1. New audience query needed? → Create Forgejo issue + board item for email_queries.py change.
    2. \n
  2. New EmailType enum value needed? → Create Forgejo issue + board item for alembic migration.
    3. \n
  3. New layout needed? → Create Forgejo issue + board item for MJML template + compile.
    4. \n
  4. All three exist? → No code needed. Proceed directly to Step 1.
    5. \n
\n

Rules

\n\n

Related

\n","is_public":true,"note_type":"sop","status":"active","parent_slug":null,"position":null,"created_by_sub":null,"created_by_name":null,"updated_by_sub":null,"updated_by_name":null,"project":{"id":5,"name":"Westside Basketball","slug":"westside-basketball","platform":"github","repo_url":"https://github.com/ldraney/west-side-basketball","is_public":true,"page_note":null,"created_at":"2026-02-26T02:00:39","updated_at":"2026-03-15T18:39:02.426531"},"tags":[{"id":5,"name":"sop"},{"id":8,"name":"active"}],"created_at":"2026-04-03T19:00:28.192523","updated_at":"2026-04-15T18:15:04.648391"}