Support service¶
Purpose¶
The support domain (backend/internal/services/support/) runs support cases: a member's request and its thread with the team. Cases come in three ways: Contact us in the app (signed in), the public form at /help/contact (no account), and email to the support mailbox, forwarded by an edge email worker. Tomoda accounts answer from Backstage (see Backstage service); a public Tomoda reply is emailed with threading headers and, for a member with an account, shows in My requests with a notification.
Aggregates¶
| Aggregate | Table | Holds |
|---|---|---|
| Case | support_cases |
Number, requester (account, address, name, language), subject, SupportCaseCategory, SupportCaseStatus (open waits on Tomoda, pending waits on the member, solved), SupportCaseSource, assignee, reply token |
| Message | support_messages |
One message: author (member or team), body, internal for Tomoda notes, the email Message-ID it came in or went out with, and the outbox columns email_kind (ack or reply) and email_sent_at |
Enums live in backend/internal/models/support.go and are mirrored in frontend/services/supportService.ts.
HTTP endpoints¶
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /support/cases |
JWT, SupportLimit |
{category, subject, body}: open a case for the caller |
| GET | /me/support/cases |
JWT | The caller's cases, newest activity first |
| GET | /me/support/cases/{id} |
JWT | One case and its public thread; another member's reads as 404 |
| POST | /me/support/cases/{id}/messages |
JWT, SupportLimit |
{body}: reply; the case goes back to open |
| POST | /support/contact |
none, SupportContactLimit |
{email, name, category, subject, body}: public form; answers {number} only |
| POST | /support/inbound |
signed | Inbound email from the edge worker (below) |
SupportLimit is 30 per hour per account; SupportContactLimit is 5 per hour per IP and fails closed.
Rules¶
- The public form can be switched off. The
support.public_formfeature switch (see Feature switches) makesPOST /support/contactanswer 503 during a spam wave; signed-in cases keep working. - The public form never links an account. Its address is unproven, so the case has no
requester_user_idand never shows in anyone's My requests. Backstage marks such cases so Tomoda accounts don't share account details there. - Acknowledgements never echo. The confirmation email carries the case number only, so the form can't be used to send arbitrary text to an arbitrary address. An unproven address gets at most one acknowledgement per 24 hours, however many cases it is named on.
- Mail goes through the outbox. A case, an acknowledgement or a Tomoda reply writes its
support_messagesrow withemail_kindset, then enqueues asupport:send_emailtask. The worker sends and stampsemail_sent_at; a provider failure retries with backoff, and a 5-minute sweep re-enqueues anything still unsent, so a lost enqueue or a provider outage never drops a reply. - Mail goes only to a proven address. For a case from the app, every email goes to the account's current address (proven at signup and on every change), not the one captured when the case opened. For a case from the form or from email,
support_cases.email_verifiedstarts false (true for email that passed DMARC) and turns true once the requester answers from that address with a DMARC pass; until then Tomoda replies stay in the thread and aren't emailed, and Backstage says so. The one acknowledgement still goes out, number only, so the requester has a reply address to prove it with. - Console changes commit with their audit row. A status change, a take or release, or a reply writes the
audit_logsrow in the same transaction (throughplatform/audit), so a failed audit never leaves a reply sent. - Tomoda accounts stay anonymous to members. Members see
teamas the author, never an id or a name; internal notes never leave Backstage. - Emails are localized into the case language (the app's
Accept-Languagewhen the case was opened; English for inbound email) across every supported language.
Problem reports¶
A problem report is a case in the bug category opened from the app: by shaking the phone, from Report on an error toast, or from Report a problem in the help center. It carries:
- Diagnostics: app version, platform, OS version, locale, the screen the member was on and the error they saw. The server keeps only known keys, each cut to its cap (
diagnosticKeysinservice.go), insupport_cases.diagnostics. - A screenshot, optional: the member picks an image, uploads it through
POST /uploads/support-screenshotand sends the key asscreenshot_key. The server checks the upload exists under the caller's own prefix. The prefix is private: members never get the image back, and Backstage shows it through a short-lived signed URL.
Email threading¶
Every email to a requester has Reply-To: support+<token>@<domain>, where the token is a random per-case secret (support_cases.thread_token, never in an API response). A Tomoda reply also carries Message-ID: <message id.case id@domain> plus In-Reply-To and References built from the case's earlier mail, so clients thread it. The sent Message-ID is stored on the message.
Inbound email¶
POST /support/inbound takes one forwarded email as JSON: message_id, in_reply_to, from, from_name, to[], subject, text, auto_submitted, and auth: {spf, dkim, dmarc}, the worker's sender authentication verdict (pass, fail, none, softfail, neutral, temperror, permerror).
- Signed.
X-Support-Timestamp(unix seconds) andX-Support-Signature(hex HMAC-SHA256 of"<timestamp>.<raw body>"withSUPPORT_INBOUND_SECRET). More than five minutes of skew, a bad signature or a missing header is 401. With no secret configured the route answers 404. - Routing. A message to
support+<token>@joins that case only when the sender is the case's requester and DMARC passed; anything else opens a new case (sourceemail, never linked to an account). The member's reply puts the case back toopen. - Authenticated. Mail without a DMARC verdict, or with DMARC
fail, answers 422INBOUND_REJECTED(final, so the worker doesn't retry) and files nothing. Each stored message keeps its verdict, which Backstage shows on the thread. - Dropped. A
message_idthis sender already delivered (redelivery; dedupe is per sender, so one sender can't block another's mail by reusing an id),auto_submittedmail and mail from the support mailbox itself are accepted and ignored. - Bounded. The body is read up to 256 KiB; text is cut to 20,000 characters.
message_idmust be one bracketed ID without whitespace (at most 250 characters inside), since later replies echo it inIn-Reply-ToandReferences; anything else is 400.
What the edge needs (devops)¶
This repository ships the API side only. To turn inbound email on, devops provides:
- Mail routing. MX records for the support domain pointing at the edge email worker, and a route that sends
support@andsupport+*@to it. - Sender checks. The worker checks SPF, DKIM and DMARC alignment and sends its verdict in
auth; the API refuses DMARC failures, and only a DMARC pass proves the sender's address. - Parsing and forwarding. The worker parses the message, sets
auto_submittedfrom theAuto-Submittedheader, strips quoted history when it can, signs the JSON body as above and POSTs it tohttps://<api host>/api/v1/support/inbound, retrying on 5xx. - The secret. A random
SUPPORT_INBOUND_SECRETin Secret Manager, shared by the worker and the API deployment. - Outbound. The transactional email domain must allow
Reply-Toon the support domain; theFromaddress stays the configured sender.
Data lifecycle¶
- A case survives the requester's deletion with
requester_user_idcleared; messages survive their author's. - Data export includes the member's cases with their public messages (
supportsection,support.NewExporter).
Dependencies (deps.go)¶
| Port | Satisfied by | Used for |
|---|---|---|
Mailer |
platform/email.Service |
Acknowledgements and threaded Tomoda replies |
Switches |
platform/switches.Service |
The support.public_form switch |
UserFinder |
user.UserStore |
The address and name for an in-app case |
notify.Notifier |
notification service | support.reply for a member with an account |
Where to look¶
| Need | File |
|---|---|
| Opening, replies, inbound routing, signatures | service.go, service_cases.go, service_inbound.go, service_mail.go |
| Cases, threads, queue | store.go, supportdb/queries.sql |
| Email templates | backend/internal/platform/email/support.go |
| Problem report capture | frontend/contexts/ProblemReportContext.tsx, frontend/utils/diagnostics.ts |
| Tomoda accounts console | backend/internal/services/backstage/cases_service.go |
| Member screens | frontend/components/support/ |