Using Support

The path a message takes

Running a support inbox is the walkthrough; the reference has every field; step 6 is classification.

  1. Mail arrives at your app Worker’s single email entry, which fans it to every capability that handles inbound mail.
  2. Support claims what is addressed to it — on the SMTP envelope recipient, never a To: header.
  3. The guard bounds it, and provenance decides whether the sender is who they claim.
  4. It is parsed — multipart and attachments included.
  5. The HTML is sanitized through the runtime’s own parser.
  6. The raw MIME goes to R2 unchanged.
  7. The row lands in D1.
  8. Only then is classification dispatched, as a Workflow — which, with search.semantic on, also embeds the message for search by meaning.

Writing in from inside the app

POST /support/feedback

Session and same-origin, and nothing else, permanently.

It opens a thread, or appends to one the caller already owns — same table, same classifier, same taxonomy, same console.

There is no second inbox, because a support person with two consoles has the whole conversation in neither.

Where your own authorization goes instead

If your account model makes some submissions act-on-behalf-of — an application made for an organization, which a member may not make — put that check in your app capability’s middleware, over your own path:

app.use("/support/feedback", async (c, next) => {
  // Signed out? Pass it through — the route's own gate answers 401. A 403 here would tell
  // somebody who was never signed in that they are forbidden.
  if (c.var.auth && !(await mayActForTheOrganization(c))) {
    throw new ForbiddenError({ message: "An owner or an admin applies on the organization's behalf." });
  }
  await next();
});

Every capability’s middleware mounts before any capability’s routes, and your app composes last — so yours runs after auth has resolved the session and before this capability’s own gate.

Write the path from the base path you configured. A mount point you moved and a middleware path you did not is a gate that silently stops covering anything.

The context the app supplies

Screen, build, platform, environment, locale — what the user should not have to type.

That set is closed. An undeclared key is refused rather than stored, because the risk of an open bag is an adopter passing their whole client state through it and quietly landing a customer’s data in an inbox a console renders.

Bounds on a public write endpoint

Because that is what a public address is:

guard: {
  maxRawBytes: 2_000_000,
  maxPerSenderPerHour: 20,
  maxPerHour: 500,
  archiveSpam: true,
}

archiveSpam is what makes the spam category do something rather than just label something.

Replying

POST /support/threads/:id/reply — control-plane, so it is an issued credential rather than a staff member’s session.

A mailed reply to an app thread is recorded with channel: "email", and the thread’s own message id is what makes the customer’s answer land back on the same thread.

A mailed reply comes from the inbox the customer wrote to, under the name of whoever answered. A thread that arrived at support@help.example.com, answered with agentName: "Jim Scott", is sent as "Jim Scott" <support@help.example.com>. Its Reply-To is reply.replyToAddress, or that same inbox when none is set. The name follows reply.fromName, {agent} by default, so {agent} at Acme sends "Jim Scott at Acme", and a name with no {agent} in it, such as Acme Support, is used for every reply. With no agent name, the email capability’s fromName is used. agentName may not contain @, <, > or ", so a display name cannot pass for an address.

A thread whose inbox is no longer in inboundAddresses, or that arrived at none, is answered from reply.replyToAddress, and refused when none is set. Support declares the addresses it sends as through email’s enqueueAs, which needs @pithy-sh/email ^0.9.0; an older one is refused at compose.

Every inbox domain has to be able to send. A domain Email Service has not onboarded fails the reply’s job with the domain named, and nothing goes out from another address in its place. pithy doctor names each inbound or reply-to domain that cannot send.

Who has it, and who else is looking

POST /support/threads/:id/assign

Control-plane, behind support:threads:assign. The body names who should have the conversation, an opaque ref and a display name, or null for nobody, and an optional note for your colleagues. Every handover is kept, and the conversation read returns the history oldest first. The inbox filters with assignee=<ref>, or assignee=none for what nobody has picked up.

Before you reply, look at the room. Each thread has a support.thread presence room, joined with the scope that already reads it. Open it with the thread, announce replying when your reply form opens, and anyone else in the room sees it before they answer the same customer.

Your own signed-in staff reach both from a session, once you name their powers in support({ staff }): POST /support/staff/threads/:id/assign behind assignPower, and the room’s session ticket behind readPower. Both powers go on roles only an operator can confer, which the reference explains.

Finding a conversation

POST /support/threads/search   { "q": "uploads keep dying" }

Control-plane, behind support:threads:read. The words go in the body, never the URL: they are often a customer’s address or order number, and a query string is written to every request log between the client and your Worker. The body is strict, so an unknown field, cursor included, is a 400. Search is its own route, not a filter on the inbox list: a query goes in, ranked threads come out, up to limit (20, at most 50), with no cursor. Keyword search finds the exact words and misses the paraphrase; semantic search finds the paraphrase and misses the order number. hybrid, the default, runs both and ranks them as one, and a tie goes to the keyword hit, so ORD-40912 still comes first. Each thread is named by its best-matching message, with that message’s raw bm25 and similarity. The inbox list’s filters go in the same body, and apply after retrieval.

Search by meaning is off until you set search: { semantic: true }, because it embeds every inbound message on your own Workers AI binding — a second inference per message. Search has every mode, field and fallback.

What you own

The mail, the database, the bucket, and the inference.

There is no Pithy-operated service in the path, and nothing here that a hosted dashboard unlocks — every route is reachable with a credential you issued, whatever anyone pays.

ESC