diff --git a/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.-.md b/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.-.md new file mode 100644 index 0000000..c629014 --- /dev/null +++ b/Repo-docs-CAMPAIGN-DELIVERY-RUNBOOK.-.md @@ -0,0 +1,84 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-campaign/docs/CAMPAIGN_DELIVERY_RUNBOOK.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Campaign Delivery Runbook + +This runbook covers controlled campaign delivery after a campaign version has +been validated, built, reviewed, and locked. + +## Operating Modes + +- Local direct send: `CELERY_ENABLED=false`. Queueing stores jobs in the DB, and + small development runs can be processed with "Send queued now". +- Worker send: `CELERY_ENABLED=true` with Redis/Celery workers running. Queueing + publishes delivery tasks, and the Review & Send page polls summary counters. +- Mock send: use only for development review. It does not prove real SMTP/IMAP + credentials or server policy. + +## Before First Live Use + +- Use dedicated non-production SMTP/IMAP credentials. +- Use a dedicated mailbox/folder for append-to-Sent tests. +- Confirm policy allows the SMTP host, envelope sender, recipients, and optional + IMAP append target. +- Run one campaign each for no attachment, one attachment, and password-protected + ZIP before using production recipients. +- Keep the report page open during tests; it is the operational source of truth + for attempts, outcomes, and reconciliation. + +## Queue And Send + +1. Validate the version with file checks enabled. +2. Build the version and inspect all blocking review items. +3. Queue only after the selected version is the intended immutable execution + version. +4. In local mode, use "Send queued now" for small test runs. +5. In worker mode, verify queue counters move from queued/claimed/sending to a + terminal SMTP state. + +## Outcome Handling + +- `smtp_accepted`: Do not retry. If IMAP append is enabled and pending, run or + enqueue the append action. +- `failed_temporary`: Retry explicitly after checking the error and retry count. +- `failed_permanent`: Retry only if the operator has corrected the root cause and + intentionally includes permanent failures. +- `outcome_unknown`: Do not retry directly. Check SMTP logs, mailbox evidence, or + provider control panels, then reconcile as accepted or not sent. +- `claimed` or `sending` that does not progress: treat as a worker interruption. + Re-run worker handling or reconcile if SMTP may already have accepted the + message. + +## Reconciliation + +- Choose "Accepted" only with external evidence that SMTP accepted the message. + The job becomes protected from retry and may proceed to IMAP append. +- Choose "Not sent" only when SMTP did not accept the message. The job becomes a + temporary failure and can be selected by explicit retry. +- Add a note that identifies the evidence used, for example SMTP log line, + provider message ID, or operator ticket. + +## Fault Injection Checklist + +Use mock infrastructure first, then repeat against the non-production real test +bed where possible: + +- SMTP temporary failure. +- SMTP permanent failure. +- Recipient refusal after partial SMTP acceptance. +- Connection drop or worker interruption during SMTP. +- IMAP append failure after SMTP acceptance. +- Worker restart with queued, claimed, and sending jobs. + +## Reporting Checks + +- Partial delivery must show accepted, failed, and unknown counts separately. +- Accepted and unknown jobs must not appear in retry selections. +- Reconciled accepted jobs must remain protected from resend. +- Reconciled not-sent jobs must appear only as explicit retry candidates. +- The final report should include SMTP attempts, IMAP append attempts, and any + reconciliation notes before the campaign is considered operationally closed.