API reference

Base host: https://api.thatsmymail.com (no /api prefix). The surface has a shared, product-agnostic layer that every product reuses, plus thin product layers built on top:

• Shared layer — /v1/* (product-agnostic): two kinds of endpoint —
  • Data — /v1/<table>/<verb>: generic, row-scoped CRUD over the backend's tables.
  • Shared services — /v1/services/<action>: cross-product business actions (e.g. POST /v1/services/sendEmail) that compose table writes in one transaction.
• Product layers — /<product>/v1/<resource>/<action>: business actions for a single product (console/auth/admin) that build on the shared layer and never reference each other.

There now is a product-agnostic /v1/* — the shared layer above. (Sending mail is the shared service POST /v1/services/sendEmail; there is no separate mail product.)

All requests are HMAC-signed — see Authentication (the signature covers the full path including the query string). Errors share one envelope — see Errors.

GET /health → { ok, service, time } is the one unauthenticated endpoint.

data — /v1/<table>/<verb>

The data layer: thin, generic CRUD over the backend's tables, on the shared product-agnostic /v1/* layer. Every call is row-scoped to your credential (an account token sees only its own projects' rows; a project key only its project's; staff/god see all). Reads return only an allowlist of columns — never secrets, password hashes, or private keys. Unknown table or verb → 404.

Tables (all in the api schema): projects, api_keys, sender_domains, webhook_endpoints, suppressions, idempotency_keys, audit_log, messages, users (self), account_tokens (own), organizations, organization_members, organization_tokens (own orgs; reads only — org create + tier changes are service actions under /console/v1/organizations).

Full CRUD, row-scoped. Gated only by row-scoping to your credential (the project_id/id you target is validated against what you own — a row you don't own returns 404) plus secret-column redaction on reads. Bodies use snake_case column names:

POST /v1/suppressions/create
{ "project_id": "…", "address": "user@example.com", "reason": "manual" }

POST /v1/projects/update
{ "id": "…", "name": "Renamed project" }

Writable tables: projects (update/delete), api_keys, sender_domains, webhook_endpoints, suppressions (create/delete), account_tokens (create/delete), and users (self-update = email change re-sets email_verified_at; self-delete = irreversible hard-delete that cascades the user's projects/keys/sender-domains/tokens, 409 if a project has sent mail). create on a secret-bearing table mints + returns the secret once. Permanent carve-outs stay service-only: messages create (a gated send — use POST /v1/services/sendEmail), audit_log (append-only), and engine tables rate_limits · webhook_deliveries · message_events (read-only). Calling a non-enabled write → 404.

auth — /auth/v1/*

Account entry point. signup and login are public (no signature) and both return the user plus a per-session account token (tmma_) to act with. logout is signed by that token and revokes it.

console — /console/v1/*

Organizations, project lifecycle and per-project configuration. The UI uses these exact endpoints.

The model: a user belongs to one or more organizations; an organization owns its projects; billing/metering lives on the organization (one daily allowance shared across its projects). The onboarding flow is Create user → Create organization → Create project → Add sender domain → Verify sender domain. A fresh signup owns no org, so the first step after auth.signup is either POST /console/v1/organizations (be the first one and create it) or — if a colleague gave them a join code — POST /console/v1/organizations/join to join an existing org. A user already in an organization cannot create another (409 already_in_organization) but may still join more with a code.

Organizations

Authorized by an account token (the member) or — for :id routes — the org's own tmmo_ token, a staff token, or the god-key. Non-members get 404 (the org's existence is never leaked).

Roles & permissions (TMM-88)

Every organization member has one of five fixed roles. Each role grants a fixed set of permission keys; a write to an endpoint whose required permission the role lacks returns 403 forbidden. (Owner-defined custom roles are a later addition.)

Permission keys gate every write. Org administration: org:manage (rename), billing:manage (plan), members:manage (invitations, join codes, member roles, removal), tokens:manage (org tokens), domains:manage (custom + sending domains). Project work: projects:manage (create/update/delete projects, webhooks, suppressions), apikeys:manage (mint/rotate/rename/revoke project API keys). Invitations and join codes carry one of the five roles; reads need no permission beyond org membership. Sending mail uses a project API key (tmm_, messages:send), not a personal account — an auditor cannot mint one (apikeys:manage), so cannot send.

The organization token (tmmo_) is the org-scoped admin credential: it authenticates AS the org and authorizes managing the org + its projects/domains/billing. It does not send mail — that stays a project key (tmm_, messages:send).

Create example

POST /console/v1/organizations
{ "name": "Acme Inc" }

{
  "organization": { "id": "…", "name": "Acme Inc", "plan": "free", "created_at": "…" },
  "organizationToken": { "id": "…", "tokenId": "tmmo_…", "secret": "…", "label": "Initial org token (auto-minted at organization creation)", "createdAt": "…", "warning": "store the secret now; it is not retrievable" }
}

Custom webmail domains — /console/v1/organizations/{id}/custom-domains (TMM-43)

Let an organization reach its webmail on its own (sub)domain (e.g. mail.acme.com) instead of the default host. The org CNAMEs the (sub)domain to mail.thatsmymail.com; once we confirm the CNAME, we serve the webmail there with automatic HTTPS. The host is platform-wide unique (like a domain claim), so two orgs can never register the same one. Authorized like the other :id org routes (member / org token / staff / god-key); non-members get 404.

A custom domain has status ∈ pending · verified · disabled. Only a verified domain is served (and only a verified one passes the on-demand-TLS ask-endpoint below, so a certificate is never issued for an unverified or someone else's host).

Create example

POST /console/v1/organizations/{id}/custom-domains
{ "domain": "mail.acme.com" }

{
  "customDomain": { "id": "…", "domain": "mail.acme.com", "status": "pending", "verified_at": null, "last_verify_attempt": null, "created_at": "…" },
  "dnsRecord": { "host": "mail.acme.com", "type": "CNAME", "value": "mail.thatsmymail.com", "note": "required — point mail.acme.com at mail.thatsmymail.com, then Verify. We then serve your webmail there with automatic HTTPS." },
  "nextStep": "Publish the CNAME, then POST /console/v1/organizations/{id}/custom-domains/{domainId}/verify."
}

Domains — claim, capabilities & inboxes (TMM-8)

A domain is a first-class, platform-wide-unique claim: once a project claims acme.com, no other project (in any org) can claim it or any subdomain. You claim the apex first, then add capabilities under it — outbound (sending, DKIM) and/or inbound (receiving, MX) — on the apex or any subdomain, plus inboxes under a verified inbound domain. (This replaces the old per-project sender-domains + inbound-domains surfaces; one domain now has exactly one owner, which fixes DKIM-key collisions across projects.)

Claims — /console/v1/projects/{id}/domains

One claim, many capabilities. You claim the apex once, then add as many Sending/Receiving capabilities as you like — on the apex or any subdomain — via the optional subdomain field. No separate claim per subdomain. Each capability is addressed by its own id (capId).

Outbound (sending / DKIM) — many per claim

Inbound (receiving / MX) — many per claim

Both at once

Inboxes (under one verified inbound capability)

Inbox billing. An inbox costs €1 per month, metered per active UTC day (≈ €1⁄30 per day, capped at €1 per inbox per month). An inbox starts billing at its first activity — the earliest of (a) the first inbound mail it receives, or (b) its first login (webmail or IMAP) — and stops when it is deleted. An inbox that is never used (no mail, never logged in) is free. The current month's total is on the org detail's inboxUsage ({ activeInboxes, billedCents, storageOverageGb, storageBilledCents, totalBilledCents, monthStart }). (The payment gate lands here later — today this only computes + displays the cost.)

Inbox storage. Every inbox includes 1 GB of storage free. You can upgrade an inbox in whole-GB steps via the storage endpoint above; each GB above the free tier bills €0.50 per month (charged on the reserved limit, summed across live inboxes into inboxUsage.storageBilledCents). When an inbox is at or over its limit, inbound mail is rejected at receive time (552 mailbox is full) — so the sender gets a clear bounce and the upgrade is how a customer makes room.

The first-party Mail webmail sends as an inbox via the platform "send-on-behalf" path (POST /v1/services/sendEmail as platform admin resolves the project from the from-address domain's verified outbound capability — unambiguous, since one outbound exists per (sub)domain platform-wide).

Projects

Create example — organizationId is required (the caller must be a member of that org):

POST /console/v1/projects
{ "name": "My App", "organizationId": "…" }

{
  "project": { "id": "…", "name": "My App", "status": "active", "plan": "free", "created_at": "…" },
  "apiKey": { "id": "…", "keyId": "tmm_…", "secret": "…", "scopes": ["project:admin"], "createdAt": "…", "warning": "store the secret now; it is not retrievable" }
}

API keys — /console/v1/projects/{id}/api-keys

New keys are platform-managed through the Adrifact tokens service — their keyId is prefixed tk_ and list rows report managed: "adrifact". Existing keys (tmm_, managed: "local") keep working unchanged. The request-signing scheme (TMM-HMAC-SHA256, see Authentication) is identical for both, so your signing code doesn't change. SDK: client.console.projects.apiKeys.create/list/update/revoke/rotate.

Webhooks — /console/v1/projects/{id}/webhooks

WebhookEvent: delivered · deferred · bounced · failed · suppressed · complained.

Suppressions — /console/v1/projects/{id}/suppressions

SuppressionReason: hard_bounce · soft_bounce_max · complaint · manual.

Project views — messages, audit, test

Owner-authorized (account token / project:admin / staff). Let the Console render a project's tabs without any platform credential.

Account tokens — /console/v1/account-tokens

Your own user-scoped credentials (tmma_) — issued at login and self-manageable here (no god-key). Authorized by the caller's own account token.

send service + message reads — /v1/services/*, /v1/messages/*

Sending and message status live on the shared /v1/* layer — sending is the shared service POST /v1/services/sendEmail; message reads are data-layer gets. Needs a project key with the matching scope.

Send example

POST /v1/services/sendEmail
{
  "to": "alice@example.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome!",
  "text": "Thanks for signing up.",
  "html": "<p>Thanks for signing up.</p>",
  "idempotencyKey": "signup-1234"
}

{ "providerMessageId": "01J…", "status": "queued" }

from may be a bare addr@domain or an RFC 5322 display name — "Acme <noreply@yourdomain.com>". Its domain must be a verified sender domain for the project, or you get sender_domain_not_verified. Sender display name: a per-message display name ("Name <addr>") always wins; if you send a bare address, the sending (sub)domain's default display name (set in the Console / via the outbound display-name endpoint below) is applied; otherwise the recipient just sees the bare address. idempotencyKey (8–128 chars) dedupes retries for 24h. MessageStatus: queued · sending · delivered · deferred · bounced · failed · suppressed.

Templates: instead of html/text, pass templateId (a templates module template in the project's org) + variables ({{var}} values) to POST /v1/services/sendEmail — the body is rendered + HTML-escaped at send time. subject is still required.

Daily quota (per organization). Every accepted message counts against the owning organization's daily allowance — 500 accepted messages/day on the free tier, shared across all the org's projects (UTC day). On a free org, message #501 today is rejected with quota_exceeded (429); upgrade the org to pay-as-you-go for unlimited sending (the first 500/day are free, the rest is metered as billable overage). See the org's usage on GET /console/v1/organizations/{id}.

Identity — GET /v1/services/whoami

A shared identity probe: tells you which principal your credential resolves to. Works with any TMM credential (project key, account token, organization token, or the platform admin key). The result is discriminated by principal. The key win for integrators: an organization token learns its own organizationId in one call, so you never have to probe org-scoped endpoints to discover it.

// organization token (tmmo_)
{ "principal": "organization_token", "organizationId": "01J…", "organization": { "id": "01J…", "name": "Acme Inc", "plan": "free" } }
// account token (tmma_)
{ "principal": "account_token", "userId": "01J…", "role": "customer", "organizations": [ { "id": "01J…", "name": "Acme Inc", "plan": "free" } ] }
// project key (tmm_)
{ "principal": "project_api_key", "projectId": "01J…", "organizationId": "01J…", "scopes": ["messages:send"] }
// platform admin key
{ "principal": "platform_admin" }

Custom-domain allow check — GET /v1/services/custom-domain-allowed (TMM-43)

A shared, unauthenticated ask-endpoint for Caddy's on-demand-TLS: before issuing a TLS certificate for an incoming webmail host, Caddy asks "is this host allowed?". It is public on purpose (Caddy can't sign a TMM request) and reveals only a boolean for the exact host queried, so there is nothing sensitive to leak.

GET /v1/services/custom-domain-allowed?domain=mail.acme.com

{ "allowed": true }

modules — /modules/<module>/v1/*

Modules are embeddable feature units that run inside the Api under their own path namespace and own their own Postgres schema. The first is templates.

templates — /modules/templates/v1/*

Organization-scoped email templates usable as a message body. Authorized by an org member's account token, the org's tmmo_ token, a staff token, or the god-key (writes are owner-gated). organizationId is in the body (POST) or query (GET).

variables is a declared list [{ name, default? }]. Each template carries is_public (bool). Use a template at send time by passing templateId + variables to POST /v1/services/sendEmail — the body is rendered from the template if it is in the sending project's organization OR public ({{name}} substitution, HTML-escaped in the html part; a private template from another org → 404). Public templates (TMM-54): a company can publish a fixed set of canonical templates that any tenant references via templateId through their own project-key — the send still goes from the caller's own project (their from-address, domain, deliverability). Visibility ≠ editability: only the owning org can edit or delete a public template.

admin — /admin/v1/*

Platform/staff operations. Authenticated with the god-key (or a staff account token) — see Authentication. Not a customer surface. Listed here for completeness; per UI/API parity these are real endpoints, not a private proxy.

Per-project configuration is not duplicated under /admin/v1/*. Staff use the same /console/v1/projects/{id}/* endpoints customers use (UI/API parity).