Support overview

Support is the employee a solo developer cannot hire. Mail arrives, and either you read all of it or you read none of it — and the tools that would help cost more per seat than the product earns.

@pithy-sh/support is an inbound support inbox that lands mail in your own D1, classifies it on your own Workers AI binding, and links each sender to the account and purchases your app already knows about.

Every piece it needs was already in the catalog. That is the point of it.

What arriving mail becomes

Mail comes in through Cloudflare Email Routing, is parsed — multipart and attachments included — and is threaded on the standard reply headers, so a conversation stays one conversation rather than five unrelated rows.

Then it is classified three ways at once: category, priority and sentiment. Three axes rather than one label is what makes a sortable inbox instead of a tagged one — angry, high priority, billing is a queue you can work, and billing alone is not.

The taxonomy is federated. Eight categories ship, and you add your own.

Classification runs on your binding

The inference lands on your bill, and your customers’ support mail never leaves your infrastructure.

That is the same argument as the rest of the kit, and it matters more here than almost anywhere: support mail is where people put their account details, their frustration, and occasionally their passwords.

Everything is derived from immutable mail

A message is what arrived. It is never edited.

So a wrong classification is recomputed, not repaired — you change the taxonomy or the model and re-derive, rather than hand-correcting rows and losing the ability to reproduce anything.

Replies go out as you

Through email, from the inbox the customer wrote to and under the name of whoever answered — "Jim Scott" <support@help.example.com> — carrying your domain, your DKIM signature and correct threading headers, which only the Worker can set. A reply that lands in the customer’s existing thread, from a person at the address they wrote to, is the difference between a support tool and a mail merge.

Two people, one inbox

A thread can be assigned to somebody, and every handover is kept. Assignment is one fact, who has this conversation, and not a status: the thread holds the current assignee, and its history holds who had it before, who has it now, who made the change and why.

A support.thread presence room shows who else has a thread open, and who is replying, so two people see each other before they answer the same customer twice. It holds nothing but who is there.

Search by words and by meaning

Keyword search finds the exact string and misses the paraphrase: a customer who writes uploads keep dying halfway never matches a search for timeout. Semantic search finds the paraphrase and misses the identifier: it cannot retrieve ORD-40912. A support inbox needs both, so support runs both and ranks them as one — and a tie goes to the keyword hit, so the order number still comes first.

Keyword search is FTS5 and on by default. Search by meaning is off until you turn it on, because it costs a second inference per inbound message on your own Workers AI binding, and you should read that before you pay it, not after. The vectors carry message ids and nothing else; the text stays in your D1. Search has the details.

The MX constraint, before you enable anything

Cloudflare Email Routing takes over a zone’s MX records.

So use a subdomain — support@help.yourdomain.com — and never your apex, or you will move your real mail off your existing provider on the day you turn Email Routing on.

That is why pithy support provision never turns Email Routing on. It routes each environment’s address by itself, to that environment’s Worker, but only for a domain you have already enabled; any other is refused by name, and everything else still provisions.

What it deliberately does not do

No status workflow. No open/pending/closed state machine, no SLA timers. That is a helpdesk product, and this is not one — if you have a support team, buy them a helpdesk.

No macros, no knowledge base. A canned reply is a starting point a person picks and edits, never something sent on its own.

No live chat, no phone, no social. Mail.

It does not read your mail for you. It sorts it. Somebody still has to answer.

The admin surface is control-plane and default-denied, which means the hosted dashboard is where a human works the queue — and a management client you wrote yourself works just as well. The one exception is your own signed-in staff: name two powers in support({ staff }) and they can assign a thread and join its room from a session.

When you would reach for it

When you are one person, or a few, and customer mail is arriving faster than you can triage it by reading every message in order.

The specific thing it buys you is the link between a sender and an account: an email address resolves to the user, their purchases and their entitlements, so is this person paying is on the screen rather than three queries away.

Not if you have a support team with a helpdesk. Not if your support volume is five messages a week — a mailbox is fine.

What it needs

It requires secrets.

Six optional capabilities each add something, and this is the most composable thing in the kit:

ComposeWhat it adds
emailReplies, going out over your own domain and DKIM
authSender-to-user resolution
paymentsPurchases and entitlements on the sender’s record
controlplaneThe admin surface a dashboard reads
storageAttachments and raw message retention
auditA trail of who read and answered what

Without email, mail arrives and is classified and nothing can reply. Without auth, a sender is an address rather than a person. Staff who work the inbox from a session need organization too, because their powers are held on its roles.

ESC