Stand up the email infrastructure — the project’s shared suppression database, a per-environment email worker, and optionally the inbound rule that routes bounces back at your app — and send one rendered template so you can see it arrive.
Synopsis
pithy email provision [--worker <name>] [--routing-zone <zone-id>] [--inbound-address <address>] [--app-worker <name>] [--json]
pithy email deprovision --env <environment> [--suppression] [--destroy-retained <n>] [--json]
pithy email test --to <address> [--template <id>] [--from <address>] [--json]This is the provisioning half of the email capability: pithy add email writes the wiring, and this command creates what the wiring points at. Once it is standing, sending a transactional email is application code.
All three subcommands reach a Cloudflare account. There is no local mode. provision has no --env flag: it spans every managed environment — staging and prod — in one run. deprovision is the opposite, and requires one: it tears down exactly the environment named. test sends a real message through the Cloudflare Email Sending API.
Its Worker deploy is gated. The Worker is deployed carrying a stamp naming the package version and a hash of its resolved configuration, and a run whose stamp matches both ships nothing. Anything the gate cannot establish — no Worker, no stamp, an unreachable account — deploys. pithy deploy --env <env> ships the same Worker without provisioning anything else, and pithy deploy --env <env> --kit --force re-uploads it regardless.
Flags
provision
| Flag | Default | Purpose |
|---|---|---|
--worker <name> | the project’s only Worker | The app Worker whose wrangler.jsonc carries the per-environment DB binding and public address |
--routing-zone <zone-id> | — | Cloudflare Zone ID of the zone that contains the address’s domain: for bounce.example.com, the parent zone example.com, where Email Routing for the subdomain is set up. Email Routing must already be enabled for the domain |
--inbound-address <address> | — | The exact recipient address the rule matches, e.g. bounce@bounce.example.com |
--app-worker <name> | — | Deployed name of the production app worker running the email() bounce handler |
--json | false | Machine-readable output |
deprovision
| Flag | Default | Purpose |
|---|---|---|
--env <environment> | none — required | The one environment to tear down, declared in pithy.config.ts. With none, or one not declared, it refuses and lists the environments it could act on |
--suppression | false | Irreversible. Also delete this project’s suppression database — every environment forgets who unsubscribed or hard-bounced. Only the last environment’s teardown may: refused while another environment still runs an email worker |
--destroy-retained <n> | — | Destructive. With --suppression, delete a list that still holds addresses. <n> must equal the count the refusal printed |
--json | false | Machine-readable output |
test
| Flag | Default | Purpose |
|---|---|---|
--to <address> | — | Required. Who receives the sample |
--template <id> | welcome | Which template to render |
--from <address> | the configured fromAddress | Override the sending address for this one message |
--json | false | Machine-readable output |
The three routing flags are all or nothing. Pass all three and the rule is created; pass none and everything else provisions with routing.skipped true. Pass one or two and the run is refused, naming the flags still missing, before anything is created.
Enabling Email Routing for a domain points its MX at Cloudflare, so the zone, the address and the target worker are an operator’s decision rather than something derived. Bounces routed back at your app are what keep the suppression list honest, which is most of deliverability. Use a subdomain, never your apex, or you will move your real mail off your existing provider. A subdomain is usually not a zone of its own: its Email Routing is set up on the parent zone, and that zone’s id is what --routing-zone takes.
The CI token holds no Email Routing grant for this rule. Email Routing Rules Write is a zone-level permission, and ci-system is granted it only on the zones holding an address a capability declares; email declares none, since the flags name it. Create the bounce rule from a signed-in session (pithy cloudflare connect), or from a token you scoped to that zone yourself.
What it does
provision, in order — and the order is the contract:
- Preflight. Verify the account can host a Workflow at all — most importantly a registered
workers.devsubdomain. - Suppression database. Create or reuse
<project>-global-email-suppressions, one per project rather than one per environment: an unsubscribe in production has to stop staging too. - Migrate it. Applied migrations skip.
- Workers. Deploy the prebuilt email worker for every ready environment, each bound to the shared suppression database and to its own environment’s resources.
- Routing rule. Last, only with all three routing flags, and only when at least one worker went up — a rule made over a run that deployed nothing starts delivering real bounce mail to a handler that is not there.
An environment is ready when its stanza in the app Worker’s wrangler.jsonc carries a DB binding with a database_id — that is, when pithy provision --env <name> has run for it. One that is not is skipped and reported, never fatal: standing staging up and proving it before production resources exist is the ordinary bring-up, and this command used to refuse it part way through, naming production, after the suppression database and staging’s worker already existed. The decision is made once, from one read, before anything is created.
Each environment’s deploy needs three things resolved first, and each missing one is refused rather than deployed around: the app DB id from that environment’s stanza; that Worker’s public address for the environment; and the environment’s secrets database, which pithy secrets provision creates.
The address is resolved through one resolver that prefers the Worker’s domains declaration, falls back to its route, then to vars.BASE_URL. Tracking and unsubscribe links are built against whatever it returns, so a Worker with none of the three is refused rather than deployed against a guess. A domains declaration the kit refuses stops provisioning outright: an invalid domain is a config error, and provisioning off the route instead would point a mail Worker somewhere you never declared. A domain is an ASCII hostname, and an internationalized one is refused, because Cloudflare Workers will not route one.
A Worker that owns what the host binds gets its own. When --worker names a Worker that lists a binding the email host binds in its ownBindings, provision deploys that Worker’s own host, <project>-<env>-<worker>---email, bound to the Worker’s own resources, and writes its Workflow bindings to reach it, <project>-<env>-<worker>---email-<job>. The shared <project>-<env>-email is left alone. Its links are built against that Worker’s address, with its theme and catalogs. See a Worker’s own kit hosts.
deprovision deletes the named environment’s send and schedule Workflows first — <project>-<env>-email-send and -email-schedule — because deleting a Worker leaves the Workflows registered against it. Then it deletes that environment’s email worker, which binds the suppression database, and then the database itself only when --suppression is passed. Every Worker’s own email host and its Workflows go beside the shared ones, found by recomputing each name from the Workers that list ownBindings, Workflows first. The global opt-out list is preserved by default; losing it is harmful. It keeps the environment’s link-signing key: pithy secrets provision created that entry and bound it into the app Worker, which is still deployed, and every link already sent is signed with it.
test renders one template through your project’s own configuration — identity, theme and all — and sends it over the Cloudflare Email Sending API. It deploys nothing.
A throwaway tracking context is built so that any template renders, including marketing templates that force an unsubscribe link, but open and click tracking are both off and no link is actually tracked: this is a visual and delivery check of your configuration. A transactional template still renders without an unsubscribe link and without a List-Unsubscribe header, tracking context or not — the kind is declared by the template, so there is no context that could add one to a sign-in message.
--json
email provision
| Key | Type | Meaning |
|---|---|---|
command | "email provision" | The subcommand that produced this line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
suppressionDatabaseId | string | The D1 id of the project’s shared suppression database, created or reused |
environments | string[] | The environments an email worker was deployed for |
skippedEnvironments | object[] | One entry per environment nothing was provisioned for |
skippedEnvironments[].env | string | The environment that was skipped |
skippedEnvironments[].reason | string | Why — env.<name> has no DB database_id. |
skippedEnvironments[].action | string | What resolves it. For any environment but production, a command that runs as written. Production takes a --confirm phrase only a person gives, so its line says the run is a person’s decision rather than naming a fix |
routing | object | What happened to the inbound Email Routing rule |
routing.created | boolean | True only when this run created the rule. False when it already existed |
routing.skipped | boolean | True when no routing flags were passed, so no rule was made |
exitCode | integer | The status the run exits with: 0. A run that provisions nothing writes no report |
One outcome, never two. A run that went ahead writes this report alone and exits 0, whether or not some environments were skipped — exitCode says so, and it matches $?. A run in which every environment was skipped provisioned no environment, so it writes nothing on stdout: the {"error":…} line on stderr is the whole answer, exit 3, with the provisioning command as its fix.
$ pithy email provision --worker api --json
{"command":"email provision","schemaVersion":1,"suppressionDatabaseId":"0f4c2a9e-5b1d-4e8a-9c3f-7a2b6d1e8f40","environments":["staging"],"routing":{"created":false,"skipped":true},"skippedEnvironments":[{"env":"prod","reason":"env.prod has no DB database_id.","action":"`pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix."}],"exitCode":0}
$ echo $?
0$ pithy email provision --worker api --json
{"error":{"code":"core/precondition_failed","status":412,"message":"No environment is ready — staging and prod have no DB database_id. It created and migrated the project's suppression database (3f7c…), which every environment shares.","action":"Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy email provision --json --worker api` again.","exit":3,"retryable":false,"fix":"pithy provision --env staging --yes"}}
$ echo $?
3The second line is on stderr, and stdout is empty.
email deprovision
| Key | Type | Meaning |
|---|---|---|
command | "email deprovision" | The subcommand that produced this line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
suppressionDeleted | boolean | Whether --suppression was passed |
email test
| Key | Type | Meaning |
|---|---|---|
command | "email test" | The subcommand that produced this line |
schemaVersion | integer | The version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one |
template | string | The template id that was rendered |
to | string | The recipient the sample was sent to |
from | string | The address it was sent from |
messageId | string | The id Cloudflare assigned the message. Absent from the line when the API returned none — the key is omitted rather than emitted as null |
Errors
Each is a problem line then an action line. Under --json it is one {"error": …} line on stderr with exit, retryable and, where the cause is known, fix, and the process exits by its class.
The capability is not configured. No Worker’s pithy.config.ts composes email. It is core/precondition_failed, exit 3. With one Worker its fix is pithy add email --worker <worker> --with-prerequisites — email declares secrets, and the Worker is named by its apps/ directory. With several there is no fix, because nothing says which Worker should compose it, and the action names one command per Worker, each runnable as written.
Credentials are missing.
No Secrets Store id. The email worker decrypts its signing key from it. All three subcommands resolve credentials through the same reader, so deprovision and test are refused without it too, though neither writes a secret.
The project has no name. The suppression database is found by name and reused, so a guessed name would adopt another project’s opt-out list.
The app Worker’s environment is not wired, or has no address for it:
api has no prod address.
Declare it in the Worker's pithy.config.ts — `domains: { prod: { pattern: "…", zone: "…" } }`. Tracking and unsubscribe links are built against it.The secrets database does not exist.
The prod secrets database (acme-prod-secrets) does not exist.
`pithy secrets provision` runs against every environment, production included. That is a person's decision, not a fix. It creates this database — the email worker binds it, and that run creates the link-signing key it signs with.An unknown template. The refusal lists every known template id.
No environment is ready. Every managed environment’s stanza lacks a DB id, so no environment was provisioned: core/precondition_failed, exit 3. The action names the provision each skipped environment needs. Its fix is pithy provision --env <env> --yes when exactly one of them is an environment an agent may provision; a production one is a person’s decision. The suppression database is the one thing the run did touch, however many environments skip, and the refusal says what it did with it, with its id: created and migrated, or reused from an earlier run.
No environment is ready — staging and prod have no DB database_id. It created and migrated the project's suppression database (3f7c…), which every environment shares.
Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy email provision --worker api` again.Several Workers and no --worker. The same input/required refusal pithy add raises, exit 2.
Examples
Provision without routing, then add the rule once the bounce subdomain exists:
$ pithy email provision
Suppression database and 2 email workers ready.
Done.pithy email provision --routing-zone 0a1b2c3d --inbound-address bounce@bounce.example.com --app-worker acme-prod --jsonSend yourself the magic-link template as your project renders it:
$ pithy email test --to sam@example.com --template magicLink
Sent "magicLink" from hello@acme.com to sam@example.com (msg-4821).
Done.Take the workers down and keep the opt-out list:
pithy email deprovision --env staging --json