pithy add support --with-prerequisites--with-prerequisites composes secrets, which support requires.
Compose email and auth too, in practice. Without email, mail arrives and is classified and nothing can reply. Without auth, a sender is an address rather than a person with purchases attached.
What lands in your repo
apps/<worker>/pithy.config.ts gains the registration, and inboundAddresses is the field to fill in:
support({
basePath: "/support",
inboundAddresses: ["support@help.example.com"],
}),That list is what claims an address, and it is what provision routes. For each environment, pithy support provision sends every address here to that environment’s Worker — the rule delivers the mail, and this declares that your Worker expects it. The config is composed per environment, so staging can claim its own address.
apps/<worker>/wrangler.jsonc gains the DB binding, in every environment stanza.
A presence room comes with it. Support declares the support.thread room kind, so add also writes the PRESENCE_ROOMS Durable Object binding, the PresenceRoom export and its class migration, and mints a local presence-ticket-key. pithy secrets provision mints the deployed ones.
Three bindings are optional and not written by add: SUPPORT_BUCKET, for attachments and raw retention; the classification Workflow, whose deployed name is per environment; and SUPPORT_VECTORIZE, the message index, only while search.semantic is on. All three arrive with provision.
Three migrations run: the first creates the message, thread and classification tables, the second adds a thread’s assignee and its assignment history, pithy_support_assignments, and the third adds pithy_support_embeddings, the model that embedded each message into the semantic index.
Read this before you provision
Cloudflare Email Routing takes over a zone’s MX records.
Use a subdomain — help.example.com — and never your apex. Turning Email Routing on for your apex moves your real inbound mail off your existing provider, on the day you turn it on. Provision never turns it on for you: it routes only a domain whose Email Routing you have already enabled.
So routing waits for you. With Email Routing off for the address’s domain, provision refuses that environment’s rule, names the domain and where to turn it on, and provisions everything else. The three routing flags, --routing-zone, --inbound-address and --app-worker, are an override for a rule the derivation would not make, and all or nothing: pass one or two and the run is refused before anything is created.
Then provision
Turn on Email Routing for the address’s domain in the Cloudflare dashboard first — a subdomain is set up under its parent zone, at Email > Email Routing > Settings > Subdomains — then:
pithy support provisionThat creates the project’s bucket, deploys the classification worker per environment, and creates or drops the full-text index in each environment’s app database to match your config — search.fts, which is on by default. A newly created index is backfilled immediately, so the inbox never answers no matches for a term plainly in a body.
Three triggers keep the index in step, created beside it on pithy_support_messages: after insert, after update and after delete. A message is indexed because it was written, not because the code that wrote it remembered. A trigger runs inside the message’s own statement, so a failed index write now fails the message write too, where it used to log a warning and carry on.
Run pithy support provision again after upgrading @pithy-sh/support. Until it has run, search falls back to a LIKE scan. A database that has the index and not the triggers is repaired and backfilled, and pithy doctor’s Support search: block names any environment still without its index or its triggers. A plain wrangler d1 export fails on a database holding the index, so back it up with pithy backup, which leaves the index out, and pithy restore rebuilds it.
Search by meaning is a second opt-in, with a price. Set search: { semantic: true } and the same command creates a Vectorize index per environment, binds it, and backfills it once from the messages you already have. Every inbound message is then embedded on your own Workers AI binding, a second inference per message on top of classification. Turn it off and the next provision drops the index. Search has how a query is answered.
Last, it routes each environment’s address. The rule goes on the zone that holds the address’s domain, the parent zone for a subdomain, and sends the exact address to the Worker pithy deploy names for that environment:
staging: staging@help.example.com now routes to acme-staging-api, on example.com.
prod: support@help.example.com now routes to acme-prod-api, on example.com.The rule is created last, deliberately. Creating it first would start delivering mail to a Worker whose classification host is not deployed yet — a window in which real customer messages arrive and stay uncategorized with nothing to say why.
pithy support is the whole command surface.
Extending the taxonomy
Eight categories ship. Yours are added rather than replacing them:
support({
categories: defineSupportCategories({
refund_request: "Wants money back",
integration_help: "Stuck wiring us into something else",
}),
}),Category, priority and sentiment are classified together on every message. Three axes rather than one label is what makes a sortable inbox rather than a tagged one.
A wrong classification is recomputed, not repaired. Everything is derived from the immutable message, so changing the taxonomy and re-deriving is the correction — there is no row to hand-edit, and that is on purpose.
Attachments are optional
With attachments off and no raw retention, no bucket is created at all and the provision step reports it as skipped.
Turn them on and SUPPORT_BUCKET is created and bound. Attachments are somebody else’s files arriving at your infrastructure, so they get the same treatment storage gives an upload.
What composing more turns on
| Compose | What appears |
|---|---|
email | Replies go out over your domain, with correct threading headers only the Worker can set |
auth | A sender resolves to a user |
payments | That user’s purchases and entitlements appear on their record |
controlplane | The admin surface a dashboard reads. Default-denied until a client is connected and granted |
storage | Attachment handling, through the object-store seam |
audit | A trail of who read and answered what, and who assigned what to whom |
organization | Your own signed-in staff, through support({ staff }): they can assign a thread and join its presence room from a session |
None is required, and each absence is a defined behavior rather than an error.
Check it worked
pithy doctor reports support under the Worker’s health.
The end-to-end check is a real message: send one to the inbound address and watch a row appear, classified. Until the routing rule exists, nothing arrives — which is the state to expect while Email Routing is off for the domain, and the reason the run names the domain it refused in as many words.