Email Pipeline

Email pipeline


Owner	Saga (Seneschal)
Last reviewed	2026-04-29 by Saga
Next review	2026-07-29
Source paths	`.agents/skills/casaconomy-cloudflare/`, `.agents/skills/casaconomy-resend/`, `workers/licensing/src/lib/email.ts`

What it is

The inbound and outbound email infrastructure for casaconomy.com. Inbound mail arrives via Cloudflare Email Routing and forwards to the regent’s Proton mailbox. Outbound mail (license keys, notifications) is sent through Resend’s API from the licensing Worker.

How it fits

Email is the “bannerstone” — the first external-facing service the keep raised, and the foundation that licensing and future user communication rest on. It sits entirely on the Cloudflare + Resend axis, requiring no additional providers.

flowchart LR
    subgraph Inbound
        Sender[External sender]
        MX[CF Email Routing<br/>casaconomy.com MX]
        Proton[Proton<br/>[email protected]]
        Sender -->|SMTP| MX
        MX -->|forward| Proton
    end

    subgraph Outbound
        LicW[Licensing Worker<br/>licenses.casaconomy.com]
        Resend[Resend API<br/>send.casaconomy.com]
        Recipient[User inbox]
        LicW -->|POST /emails| Resend
        Resend -->|SMTP via SES| Recipient
    end

    subgraph DNS["Cloudflare DNS"]
        SPF[SPF records]
        DKIM[DKIM keys]
        DMARC[DMARC policy]
    end

    MX -.->|validated by| SPF
    Resend -.->|signs with| DKIM
    Recipient -.->|checks| DMARC

Components

Source	Responsibility
`.agents/skills/casaconomy-cloudflare/references/zone.md`	Canonical DNS + Email Routing state (source of truth)
`.agents/skills/casaconomy-cloudflare/scripts/cf`	Operator CLI for CF zone: MX records, routing rules, destinations
`.agents/skills/casaconomy-resend/references/account.md`	Canonical Resend state: domain, tokens, aliases
`.agents/skills/casaconomy-resend/scripts/resend`	Operator CLI for Resend: send, verify domains, check delivery
`workers/licensing/src/lib/email.ts`	Production send functions: `sendWelcomeEmail()`, `sendRevocationEmail()`
`workers/licensing/src/handlers/access_request.ts`	Trigger: license issuance calls `sendWelcomeEmail()`

Data flow

Inbound path

External sender delivers to hello@, support@, or [email protected]
CF MX records (route{1,2,3}.mx.cloudflare.net, priority 43/48/51) accept delivery
CF Email Routing evaluates rules — all addresses plus catch-all forward to [email protected]
Proton receives and stores. Regent reads on phone or desktop.

Outbound path (license delivery)

sequenceDiagram
    participant U as User
    participant W as Licensing Worker
    participant R as Resend API
    participant S as AWS SES (eu-west-1)
    participant I as User inbox

    U->>W: POST /v1/access-requests {email}
    W->>W: generate license key, store in D1
    W->>R: POST /emails {from: licenses@, to: user, key}
    R->>S: relay via SES
    S->>I: deliver with DKIM signature
    Note over I: SPF passes (envelope-from: send.casaconomy.com)
    Note over I: DKIM passes (resend._domainkey.casaconomy.com)
    Note over I: DMARC passes (p=none → monitor)

DNS authentication records

The domain split isolates inbound and outbound SPF without collision.

Type	Name	Purpose
MX (3 records)	`casaconomy.com`	CF Email Routing acceptance
TXT (SPF)	`casaconomy.com`	`include:_spf.mx.cloudflare.net ~all` — inbound only
TXT (DKIM)	`cf2024-1._domainkey.casaconomy.com`	CF Email Routing DKIM for forwarded mail
MX	`send.casaconomy.com`	SES bounce feedback path
TXT (SPF)	`send.casaconomy.com`	`include:amazonses.com ~all` — outbound envelope-from
TXT (DKIM)	`resend._domainkey.casaconomy.com`	Resend DKIM for From-header domain
TXT (DMARC)	`_dmarc.casaconomy.com`	`v=DMARC1; p=none; rua=mailto:[email protected]; aspf=s; adkim=s`

Why the subdomain split works: SPF checks the envelope-from (send.casaconomy.com), while DKIM and DMARC check the From-header domain (casaconomy.com). Each authentication mechanism validates against the right scope without interference.

DMARC ratchet plan: p=none (monitor) → p=quarantine after 1 clean week of aggregate reports → p=reject after 2 more clean weeks. Aggregate reports arrive at [email protected].

Secrets and tokens

All secrets are machine-local, never committed.

Secret	Scope	Storage
`CLOUDFLARE_API_TOKEN`	Zone:DNS:Edit, Zone:Email Routing Rules:Edit	`~/.paperclip/secrets/cloudflare.env`
`RESEND_API_TOKEN`	Send-only (production code + Worker)	`~/.paperclip/secrets/resend.env` + `wrangler secret`
`RESEND_ADMIN_TOKEN`	Full access (operator tasks, revoked between sessions)	`~/.paperclip/secrets/resend.env`

Failure modes + recovery

Failure	What happens	Recovery
CF Email Routing destination unverified	Inbound mail silently dropped	Re-verify via `cf email destinations`; check regent’s Proton spam
Resend API token expired/revoked	Outbound sends fail with 401; Worker returns 500 to caller	Rotate token in Resend dashboard, update `wrangler secret put RESEND_API_TOKEN`
DKIM key rotation	Old key still valid during overlap; no gap	Resend handles rotation; verify via `resend domains records`
DMARC reject on legitimate mail	Mail quarantined or rejected by recipient	Check `rua` aggregate reports; if false positive, relax DMARC back to `p=quarantine`
SES bounce rate too high	Resend / SES may throttle or suspend sending	Monitor Resend dashboard; clean recipient list

What’s planned to change

DMARC ratchet — move from p=none to p=reject once aggregate reports show clean alignment (tracked manually, no CAS yet).
CAS-1093 (sync) — sync notifications may add a second outbound email trigger from sync.casaconomy.com Worker.
CAS-1100 (licensing tiers) — paid tier emails (receipts, renewal reminders) will add templates to workers/licensing/src/lib/email.ts.

Last reviewed: 2026-04-29 by Saga. Next review: 2026-07-29.

What changed {#what-changed}

This chapter was introduced in CAS-3637 Phase 3 (The Casaconomy Book) as the canonical reference for the email infrastructure.

See: CHANGELOG → 2026-05-18