# 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.
- Start the repository test bed in `dev/mail-testbed/` when a local
  production-like SMTP/IMAP server is sufficient.
- 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.

## Deliverability Preflight

Before the first live send for a sender domain or mail-server profile:

- Confirm the selected SMTP identity matches the visible From/envelope sender
  policy.
- Confirm SPF, DKIM, and DMARC are handled by the sending infrastructure or
  documented as out of scope for the selected test environment.
- Confirm rate limits are explicitly set for the expected provider and recipient
  volume.
- Confirm bounce/reply/notification addresses are monitored by an operational
  mailbox or intentionally disabled.
- Confirm large attachments and password-protected ZIPs are acceptable for the
  recipient systems.
- Confirm owner transfer or policy changes force profile reselection and
  revalidation before live delivery.

## 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 CSV export should include message id, resolved envelope headers,
  attachment evidence, EML reference/checksum, latest SMTP response/error, and
  latest IMAP folder/error before the campaign is considered operationally
  closed.