Skip to content

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_form feature switch (see Feature switches) makes POST /support/contact answer 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_id and 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_messages row with email_kind set, then enqueues a support:send_email task. The worker sends and stamps email_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_verified starts 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_logs row in the same transaction (through platform/audit), so a failed audit never leaves a reply sent.
  • Tomoda accounts stay anonymous to members. Members see team as the author, never an id or a name; internal notes never leave Backstage.
  • Emails are localized into the case language (the app's Accept-Language when 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 (diagnosticKeys in service.go), in support_cases.diagnostics.
  • A screenshot, optional: the member picks an image, uploads it through POST /uploads/support-screenshot and sends the key as screenshot_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) and X-Support-Signature (hex HMAC-SHA256 of "<timestamp>.<raw body>" with SUPPORT_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 (source email, never linked to an account). The member's reply puts the case back to open.
  • Authenticated. Mail without a DMARC verdict, or with DMARC fail, answers 422 INBOUND_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_id this sender already delivered (redelivery; dedupe is per sender, so one sender can't block another's mail by reusing an id), auto_submitted mail 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_id must be one bracketed ID without whitespace (at most 250 characters inside), since later replies echo it in In-Reply-To and References; anything else is 400.

What the edge needs (devops)

This repository ships the API side only. To turn inbound email on, devops provides:

  1. Mail routing. MX records for the support domain pointing at the edge email worker, and a route that sends support@ and support+*@ to it.
  2. 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.
  3. Parsing and forwarding. The worker parses the message, sets auto_submitted from the Auto-Submitted header, strips quoted history when it can, signs the JSON body as above and POSTs it to https://<api host>/api/v1/support/inbound, retrying on 5xx.
  4. The secret. A random SUPPORT_INBOUND_SECRET in Secret Manager, shared by the worker and the API deployment.
  5. Outbound. The transactional email domain must allow Reply-To on the support domain; the From address stays the configured sender.

Data lifecycle

  • A case survives the requester's deletion with requester_user_id cleared; messages survive their author's.
  • Data export includes the member's cases with their public messages (support section, 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/