SDK reference

@thatsmymail/sdk — the official TypeScript SDK. Zero runtime dependencies (native fetch + node:crypto), full type definitions, HMAC signing built in.

It mirrors the API paths 1:1. Product layers map as client.<product>.<resource>.<action>() → /<product>/v1/<resource>/<action>. The shared, product-agnostic layer maps as client.v1.<table>.<verb>() → /v1/<table>/<verb> (data) and client.v1.services.<action>() → /v1/services/<action> (shared services, e.g. client.v1.services.sendEmail()). Path params (:id) are leading arguments. If you can read the call, you know the URL.

v0.17.0 is a breaking change (alpha — still 0.x). The old client mail and api accessors are removed; the data layer + a new shared-services accessor move to the product-agnostic client.v1.*. Migrate as follows: the old top-level mail send becomes client.v1.services.sendEmail(msg); the old mail message reads become client.v1.messages.get(id) / client.v1.messages.events(id); and the old per-table api accessor becomes client.v1.<table>.<verb>(). Other products (client.console.*, client.admin.*, client.auth.*, client.modules.templates.*) are unchanged.

v0.5.0 is a breaking change from 0.4.x: the flat surface (client.send, client.project(id), client.messages, client.projects) is gone — everything now lives under client.console.* / the shared send service (later client.v1.services.sendEmail).

v0.7.0 (additive): adds client.auth.* (signup/login/logout), client.console.projects.senderDomains.* (multiple sender domains per project), and makes keyId/secret optional for an auth-only client.

v0.8.0: product-first URLs (services moved to /<product>/v1/*) — SDK method names are unchanged, only the URLs they hit. Adds the generic data layer client.v1.<table>.{get,list}() (/v1/<table>/*, row-scoped + secret-redacted) and client.admin.* (/admin/v1/*).

v0.9.0 (additive): the data layer gains WRITES — client.v1.<table>.create(body) and .delete(body) (POST /v1/<table>/{create,delete}). Server-side these are allowlisted to safe single-table writes (currently suppressions); the project_id in the body is validated against your credential, and all other tables' writes stay service-only.

v0.10.0 (additive): data layer is full CRUD — adds client.v1.<table>.update(body) and .upsert(body); .delete(body) now returns { ok: true }. Writes are row-scoped to your credential; enabled across the tenant tables (suppressions, projects, api_keys, account_tokens, webhook_endpoints, sender_domains). Permanent carve-outs stay service-only/read-only: messages create (use v1.services.sendEmail), audit_log (append-only), and the engine tables rate_limits/webhook_deliveries/message_events.

v0.11.0 (breaking, data layer only): the data layer is now product-first — client.v1.<table> moves to a product-scoped accessor; the product-agnostic /v1/* is retired.

v0.12.0 (breaking, data layer only): the data layer collapses to a single api product data accessor (later superseded by the shared client.v1.* in v0.17.0). The backend's tables all live in one Postgres schema (the separable unit); console/auth are service facets, not schemas, so the per-product data split from 0.11.0 was wrong. Service-layer calls are unchanged. Tables: projects, api_keys, sender_domains, webhook_endpoints, suppressions, idempotency_keys, audit_log, messages, users, account_tokens.

v0.13.0 (additive + one small breaking change): organizations — the ownership + billing layer. Adds client.console.organizations.{create,list,get,setPlan} and client.console.organizations.tokens.{create,list,revoke}, plus the data-layer reads client.v1.{organizations,organization_members,organization_tokens}. Breaking: client.console.projects.create() now requires { name, organizationId } (a project is created under an org), and .list() takes an optional { organizationId } filter. Quota: sending on a free org throws quota_exceeded (429) at 500 accepted messages/day.

v0.14.0 (additive): password reset/change — client.auth.password.forgot(email) (public; always resolves, emails a reset link), .reset(token, password) (public; consumes the emailed token), and .change(currentPassword, newPassword) (account token; logged-in change). Reset emails are sent by TMM itself from notification@noreply.thatsmymail.com.

v0.15.0 (additive): organization management — client.console.organizations.update(id, { name }) (rename), .invitations.{create,list,revoke} + .acceptInvitation(token) (invite teammates by email; the accept link is emailed and returned to copy), and .members.remove(id, userId).

v0.16.0 (additive): the templates module — client.modules.templates.{create,list,get,update,delete,render} (org-scoped reusable email bodies with {{variables}}), plus v1.services.sendEmail now accepts templateId + variables to render the body from a stored template at send time.

v0.29.0 (additive): custom webmail domains (TMM-43) — client.console.organizations.customDomains.{create,list,verify,delete}. An org registers an own (sub)domain CNAME'd to the webmail; once verify confirms the CNAME, the webmail is served there with automatic HTTPS. create returns the CNAME record to publish.

v0.38.0 (additive): organization join codes (TMM-86) — client.console.organizations.joinCodes.{create,list,revoke} and client.console.organizations.join(code). An owner generates a one-time code (with a role) to onboard a colleague, who redeems it to join the org. Also (TMM-87): client.console.organizations.create() now throws 409 already_in_organization if the caller already belongs to an organization — join an existing one with a code instead.

v0.39.0 (additive): organization roles & permissions (TMM-88) — five fixed roles (owner/admin/member/ auditor/billing). client.console.organizations.members.setRole(id, userId, role) changes a member's role, client.console.organizations.roles() returns the static role → permissions matrix, and invitations + join codes now accept any of the five roles. A write whose permission your role lacks returns 403 forbidden.

Install

Private package on GitHub Packages. Your project needs a .npmrc:

@adrikesteren:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

pnpm add @thatsmymail/sdk   # GITHUB_TOKEN needs read:packages

Construct a client

import { TmmClient } from "@thatsmymail/sdk";

const tmm = new TmmClient({
  keyId:  process.env.TMM_KEY_ID!,   // public id (tmm_… / tmma_…)
  secret: process.env.TMM_SECRET!,   // HMAC secret — treat like a password
  // baseUrl: "http://localhost:18001",  // optional; defaults to https://api.thatsmymail.com
  // timeoutMs: 30000,                    // optional
});

One client = one credential = one environment. The credential you pass decides what you can call (the server authorizes per endpoint) — a project key for v1.services.sendEmail, an account token for console.projects.create/list. See Authentication.

keyId/secret are optional: construct new TmmClient() with no credentials to call the public tmm.auth.signup() / tmm.auth.login(), which return the account token you then build a full client with.

Surface

Examples

Log in, then act as the user (no credentials needed to log in):

const auth = new TmmClient();                       // no keyId/secret → auth-only
const { user, accountToken } = await auth.login({ email, password });
const tmm = new TmmClient({ keyId: accountToken.tokenId, secret: accountToken.secret });
const projects = await tmm.console.projects.list();
// …end the session:
await tmm.auth.logout();                             // revokes accountToken

Send a message (project key, messages:send):

const { providerMessageId, status } = await tmm.v1.services.sendEmail({
  to: "alice@example.com",
  from: "noreply@yourdomain.com",
  subject: "Welcome!",
  text: "Thanks for signing up.",
});

Who am I? (any credential) — resolve the calling principal. An organization token gets its own organizationId back, so an integrator signing with a tmmo_ token no longer has to probe org-scoped endpoints to find which org it controls:

const me = await tmm.v1.services.whoami();
if (me.principal === "organization_token") {
  console.log(me.organizationId); // the org this tmmo_ token controls
}

Onboard: create an org, then a project under it (account token):

// A fresh account owns no organization yet — create one first.
const { organization, organizationToken } = await tmm.console.organizations.create({ name: "Acme Inc" });
// store organizationToken.secret now — the org-scoped admin credential (tmmo_), shown once

// Projects are created UNDER an organization (billing/quota live on the org):
const { project, apiKey } = await tmm.console.projects.create({
  name: "My App",
  organizationId: organization.id,
});
// store apiKey.secret now — it is not retrievable again
const key = await tmm.console.projects.apiKeys.create(project.id, {
  label: "server",
  scopes: ["messages:send", "messages:read"],
});

Check today's usage / switch tier (the daily allowance is per organization):

const { usage, inboxUsage } = await tmm.console.organizations.get(organization.id);
// usage      = { tier, dailyLimit: 500, usedToday, remaining, overageToday }  — messages today
// inboxUsage = { activeInboxes, billedCents, storageOverageGb, storageBilledCents, totalBilledCents, monthStart }
//   billedCents = inbox-days (€1/inbox/mo); storageBilledCents = extra storage (€0.50/GB/mo above 1 GB free); totalBilledCents = sum
await tmm.console.organizations.setPlan(organization.id, "payg"); // owner only — lifts the daily cap

Claim a domain, then set up sending (project:admin):

// 1. Claim the apex ONCE (publish the ownership TXT it returns, then verify)
const claim = await tmm.console.projects.domains.claim(project.id, { domain: "example.com" });
// publish claim.dnsRecords.ownership, then:
await tmm.console.projects.domains.verify(project.id, claim.id);

// 2. Add sending on a subdomain — noreply.example.com — under the SAME claim
const updated = await tmm.console.projects.domains.addOutbound(project.id, claim.id, { subdomain: "noreply" });
const cap = updated.outbound.find((o) => o.domain === "noreply.example.com")!;
// publish cap.dnsRecords.{dkim,spf,dmarc}, then verify THAT capability by its id:
await tmm.console.projects.domains.verifyOutbound(project.id, claim.id, cap.id);

// (or set up sending + receiving for one (sub)domain in a single call)
await tmm.console.projects.domains.addCapabilities(project.id, claim.id, { subdomain: "mail" });

Custom webmail domain (TMM-43) — let an org reach its webmail on its own host:

// 1. Register the (sub)domain; publish the CNAME it returns.
const { customDomain, dnsRecord } = await tmm.console.organizations.customDomains.create(
  organization.id,
  { domain: "mail.acme.com" },
);
// dnsRecord = { host: "mail.acme.com", type: "CNAME", value: "mail.thatsmymail.com", … }

// 2. Once the CNAME is live, verify it. After this we serve the webmail there with auto-HTTPS.
await tmm.console.organizations.customDomains.verify(organization.id, customDomain.id);
// → { status: "verified", domain: "mail.acme.com" } (throws `cname_not_found` until it points at us)

const domains = await tmm.console.organizations.customDomains.list(organization.id);

Wrapping for a Mailer interface (the SDK has no top-level send() — sending is the shared service):

import { TmmClient, type MailMessage, type MailerResult } from "@thatsmymail/sdk";
const tmm = new TmmClient({ keyId, secret });
const mailer = { send: (m: MailMessage): Promise<MailerResult> => tmm.v1.services.sendEmail(m) };

Errors

Every failure throws a TmmError (code, status, message, details?, requestId?). See Errors.

import { TmmError } from "@thatsmymail/sdk";
try {
  await tmm.v1.services.sendEmail({ /* … */ });
} catch (err) {
  if (err instanceof TmmError) console.error(err.code, err.status, err.requestId);
  else throw err;
}