Skip to content

Email

Transactional email is sent through the Resend HTTP API rather than direct SMTP. Source: backend/internal/platform/email/. The public event-share OG page template lives in backend/templates/og.html; email bodies are built in Go.

Service overview

email.Service is a thin HTTP client that POSTs JSON to Resend's send endpoint:

type Request struct {
    From    string   `json:"from"`
    To      []string `json:"to"`
    Subject string   `json:"subject"`
    HTML    string   `json:"html"`
    Text    string   `json:"text,omitempty"` // plain-text part
}

The endpoint URL and auth key come from config.Email:

Field Source Notes
Email.APIKey EMAIL_APIKEY env var Resend API key (sending access, restricted to tomoda.life)
Email.BaseURL YAML (email.base_url) https://api.resend.com/emails in every environment
Email.From YAML (email.from) Default From address (config.prod.yaml sends as Tomoda, from the no-reply mailbox)
Email.AllowPrivate YAML (email.allow_private) Permits private-range hosts; tests only, since Resend is a public API
Email.LogoBaseURL YAML (email.logo_base_url) Logo host for local dev; elsewhere the logo loads from ObjectStorage.PublicURL

The client is built by httpx.NewSafeClient with a 30-second timeout and SSRF guards (private ranges blocked unless AllowPrivate is set). A non-2xx response returns an *email.APIError carrying the status, Resend's error name and message, and on a 429 the retry-after delay. There is no transport-level retry; that is left to callers where failure matters (see Rate limits and quota).

Provider

The provider is Resend. SendMessage posts to POST https://api.resend.com/emails with Authorization: Bearer {api_key}; Resend answers 200 with {"id": "..."}. An error body is {"statusCode": 422, "name": "validation_error", "message": "..."}. The message can echo recipient details, so logs carry only the status and name.

The sending domain is tomoda.life, verified in Resend through the DKIM and send. MX/SPF records in the devops repo (infrastructure/cloudflare/dns.tf). EMAIL_APIKEY comes from the Secret Manager secret tomoda-email-api-key, synced by ExternalSecrets in dev and prod.

Rate limits and quota

Resend allows 10 requests per second per team, shared by every key (dev and prod included), and answers 429 rate_limit_exceeded with a retry-after header past that. Plan quotas also return 429, as daily_quota_exceeded or monthly_quota_exceeded.

Caller On a rate limit or 5xx On a quota error
Verification code 503 OTP_SEND_FAILED; the client retries Same
Welcome, deactivation, account linked Logged and dropped (best effort) Same
Policy notice Up to 3 attempts per recipient, waiting at least retry-after (capped at 30 s); a recipient that still fails is released and the task errors so the queue retries The run stops and the task errors, so the queue retries later without failing every remaining recipient

The notice is paced by legal.policy_notice_rate (4 per second in prod), which leaves headroom under the team limit for verification codes sent while it runs. APIError.Retryable is true for 429 (except quota errors) and 5xx.

Required config

SendEmail returns "email API key not configured" or "email base URL not configured" when these are blank. In local dev without secrets, email-dependent flows (OTP, password reset, email change) fail.

Templates

Each email is inline-styled HTML from a Render* function (email.go, policy_notice.go) wrapped in one shared layout (wrapEmailHTML plus baseEmailStyles()): one neutral light palette (grey header, white card, gold #A9611F accents) with no dark-mode hints, so each client derives its own dark version; neutral greys invert cleanly where warm tints went muddy or green. The footer links Privacy, Terms and Help on tomoda.life. The header shows the ember logo from {logo base}/email-logo-ember.png in every mode, above the gold wordmark; with no logo host the wordmark stands alone. No web fonts load. Every interpolated value (name, code, URL, summary) is HTML-escaped.

Use cases

Email Sent when Language from
Verification code (SendOTPEmail) POST /auth/otp/send (signup, password reset, account deletion, data export) and POST /auth/email/change Signup: the request's Accept-Language. Other purposes: the saved language of the account that owns the address (for an email change, the signed-in account), else Accept-Language
Welcome (SendWelcomeEmail) Email registration (POST /auth/register) The request's Accept-Language
Account deactivation (SendAccountDeactivationEmail) DELETE /auth/profile, or Apple's consent-revoked / account-delete notification The account's saved language
Account linked (SendAccountLinkedEmail) POST /auth/links/personal succeeds: tells the personal account a Tomoda team account was linked to it The personal account's saved language, else Accept-Language
Policy notice (SendPolicyUpdateEmail) The legal:policy_notice async task, enqueued when the prod workers start on the release that ships a manifest version with a notice block, 30 days before it takes effect (required service notice to every live account; HTML plus plain text) The account's saved language
Suspension review (SendSuspensionReviewEmail) Staff undo or keep a suspension a member asked to have reviewed (or restore a member with an open request): says the account is active again, or the suspension stays. A suspended member has no session, so email is how they learn it The account's saved language

email.Service is a platform singleton wired in ServiceSet; the auth domain and the async policy-notice handler are its callers. See the Auth service and Async.

Localization

Every member-facing email renders in the member's language. Each Send* and Render* function takes an email.Locale.

Choosing the language. mailLocale (backend/internal/services/auth/auth_service.go, over email.ResolveLocale) picks the saved profile language (user_profiles.language) when it matches a supported locale, else negotiates the request's Accept-Language header (the app sends its UI language there), else English. The notice job has no request, so it uses the saved language or English. email.MatchLocale normalizes one BCP 47 tag: case and _ are ignored, regional variants fold into their base (ja-JP to ja, en-US to en, pt-BR and pt-PT to pt), Chinese splits by script (zh-TW, zh-HK, zh-Hant to zh-Hant; zh, zh-CN, zh-Hans to zh-Hans), nb and nn map to no, and legacy iw / in map to he / id. Anything else falls back to English.

Supported locales. The 27 entries of email.Locales, one per language a member can pick in the app (LANGUAGES in frontend/i18n/languages.ts, saved to user_profiles.language; models.IsProfileLanguage accepts exactly those codes): en, ja, zh-Hans, zh-Hant, es, hi, pt, ar, ru, fr, de, ko, vi, id, tr, it, th, pl, nl, uk, sv, he, el, cs, da, fi, no. TestLocales_MatchTheAppLanguagePicker keeps the two lists in step. Arabic and Hebrew render right to left (dir="rtl" on <html> and <body>, start-aligned text on the right).

Catalog. Strings live in locales/<locale>.json, one embedded file per locale, decoded into the typed messages struct in catalog.go; the templates keep the HTML and read fields from it. A key missing or blank in a locale falls back to English at load. In a string, {name}-style slots are filled at render time and **text** marks emphasis (rendered as <strong class="emphasis">). Catalog text is HTML-escaped before the slots are filled, so a translation cannot inject markup. "Tomoda" stays untranslated. Every visible string is translated, including the footer, header labels and the in-app path to the account screen, built as nav_hub → nav_account. In every language the two words are the app's own (navigation.hub in frontend/i18n/locales/<code>/common.json, hub.nav.account in hub.json), and TestCatalogs_NavWordsMatchTheAppBundles fails when they drift. The policy titles (doc_*) are the app's legal.docs.* from website.json (TestCatalogs_DocTitlesMatchTheAppBundles), and every sentence about the account uses the app's word for it (TestCatalogs_AccountWordMatchesTheApp).

Dates. The notice's effective date is formatted per locale from the table in dates.go (month names in the grammatical form each pattern needs; Thai uses the Buddhist Era year), always as the UTC calendar date.

Numbers. Catalog text holds no digits: counts are slots ({minutes}, {days}) filled by formatNumber (numbers.go, golang.org/x/text/number), which writes each locale's CLDR default numbering system without grouping. For ar that is Arabic-Indic digits (٠-٩), so Arabic emails show ١٠ دقائق and ٢٠ نوفمبر ٢٠٢٦; every other supported locale uses ASCII digits. Dates, the welcome step numbers and the copyright year go through the same function. The copyright year is always Gregorian, Thai included. Verification codes, URLs and addresses stay ASCII.

Policy summaries. The manifest's notice.summary is English, and every notice must also carry summary_translations with exactly one entry per LANGUAGES code other than en-US ("ja-JP", "zh-CN", "zh-TW", "pt", "no", ...); models.ParseLegalManifest rejects a notice with a missing or extra key, so the server will not start with one. Rendering still falls back to the English summary for a locale with no translation, as a safety net only.

Untranslated-text guard. TestRenderEmails_NoEnglishLeftInTranslatedLocales renders every email, subject and plain-text part in every non-English locale and fails when a visible text node, alt or title equals the English rendering's, or contains an English phrase of two or more words. Only the brand, the sample name and code, the support address and URLs are allowed through.

Adding a language.

  1. Add the language to LANGUAGES in frontend/i18n/languages.ts and to profileLanguages in backend/internal/models/user_profile.go, then add the Locale constant, list it in email.Locales (locale.go) and the picker test; extend MatchLocale if the tag needs special folding.
  2. Copy locales/en.json to locales/<locale>.json and translate every value, keeping each {slot} and **emphasis**, and add the language's summary to testdata/sample_summaries.json.
  3. Add its long-date pattern and month names to dateStyles (dates.go).
  4. Run go test ./internal/platform/email/...: it fails on a missing locale file, a key missing from or extra in any file, a dropped slot or emphasis marker, a missing date style, or an em dash.