Email & Outreach Flows
Why this folder exists
On 2026-04-13, a pastor received a lifecycle email with a "Manage My Subscription" CTA that silently redirected him to the ChurchWiseAI homepage instead of his dashboard. The bug had been in production for weeks. Every QA pass ("go-live ready") had missed it. The test suite clicked buttons in the UI; it never read an email and followed a link.
This folder fixes that failure mode by requiring every email flow to be:
- Documented end-to-end — trigger through destination, with exact file paths, DB columns, and expected content.
- Verifiable at every step — each step names the check that proves it works, using the shared vocabulary in
_verification-vocab.md. - Compliance-annotated — CASL / CAN-SPAM clauses called out at the step that enforces them.
If a flow file says "Step 5: Gmail delivers the email" without a delivered: verification entry, the flow is not complete. Incomplete flows must not be declared launch-ready.
How to read a flow file
Every flow file uses _template.md. The critical sections:
| Section | What it answers |
|---|---|
| Trigger | What causes the email to fire? |
| Preconditions | What state must exist before trigger fires? |
| Steps | What happens, in order, with code/DB references |
| Verifications | For each step, the exact check that proves it works |
| Failure modes | Known ways this breaks + the alert that catches it |
| Unsubscribe / DNC | Which email_do_not_contact or opt-out flag gates this flow |
Running the verifications
Each flow's verifications map to tests / commands / MCP calls. See _verification-vocab.md for the exact tool each verb invokes.
The QA orchestrator surfaces flows via /qa email-flows (planned). Individual flow verification: /qa flow:<flow-id>.
Current flow inventory
Priority order is set by the founder. Cold outreach (PewSearch Pro Website, active this week) is #1. Then customer lifecycle, then marketing, then ops.
Cold outreach (priority 1)
| Flow | Status | File |
|---|---|---|
| No-website → Pro Website pitch (2026-04 campaign) | DRAFTED | cold-outreach-no-website-pro-website.md |
| Unsubscribe & global DNC gating (cross-cutting) | DRAFTED | unsubscribe-and-dnc-gating.md |
| Reply triage (auto-responder + founder routing) | TODO | — |
| Bounce handling | TODO | — |
| Kill-switch (3% unsub rolling 24h) | TODO | — |
Customer lifecycle (priority 2)
| Flow | Status | File |
|---|---|---|
| Signup → Welcome (Stripe webhook) | TODO | — |
| Day 2 / 5 / 7 onboarding (cron) | TODO | — |
Trial-ending (Stripe trial_will_end + day-13 cron) | TODO | — |
| Payment failed | TODO | — |
| Cancellation scheduled | TODO | — |
| Phone number provisioned | TODO | — |
| Team member invite | TODO | — |
| Day-30 checkin | TODO | — |
| Winback | TODO | — |
Marketing (priority 3)
| Flow | Status | File |
|---|---|---|
| Newsletter welcome + 3-day sequence | TODO | — |
| AI Ministry Course (7-day) | TODO | — |
| AI Starter Kit nurture (3 emails) | TODO | — |
| Cross-promo between properties | TODO | — |
Ops (priority 4)
| Flow | Status | File |
|---|---|---|
| Founder action SMS + email | TODO | — |
| Voice setup alert | TODO | — |
| New sale notification (internal) | TODO | — |
| Payment received (internal) | TODO | — |
Conventions
- File names: kebab-case, describe the flow's purpose, not its trigger.
cold-outreach-no-website-pro-website.mdnotpewsearch-campaign-apr.md. - Underscored files (
_template.md,_verification-vocab.md) are meta — reference material, not flows. - Status markers:
DRAFTED(written, awaiting verification pass),VERIFIED(every step's check passes against prod),STALE(code has moved; doc needs update). OnlyVERIFIEDflows count toward "launch-ready." - Don't duplicate the code. Link to
route.ts/ table columns by path. The flow file is the story, the code is the truth.