Knowledge base
REST API
A documented HTTP API with issuable, scopable, revocable keys.
Details
- On, everywhere. The API serves 548 documented operations across 404 paths (emails, threads, drafts, labels, contacts, audiences, sign-up forms, broadcasts, domains, the web app address, templates, rules, roles, members, suppressions, files, settings, calendar, tracking, webhooks and the account) behind a committed OpenAPI 3.1 document you can read without a key at GET /openapi.json. Access is decided by the workspace key you issue in Settings.
- The durability this used to be waiting on is done. A send writes a row before anything is dispatched, with a public id of the form msg_ followed by 24 hex, and GET /emails/{id} resolves it, along with /events for the per-recipient trail and /tracking for opens and clicks. An Idempotency-Key of 1–255 characters is claimed against a unique index on the key and your API key together, so a retry after a timeout returns the first result with Idempotency-Replayed: true rather than sending twice. A keyed send answers 200 once it has settled and 202 while it is still queued or scheduled.
- Keys are minted, scoped, rotated and revoked in Settings → API keys. A key carries a send scope of up to 25 whole domains and 50 single addresses, where a whole domain also covers addresses added to it later, an optional expiry between 1 and 3650 days, and optionally a role. The role is a ceiling rather than a second grant: GET /ping returns both the scopes on the key and the scopes the role left it, so a 403 for a scope your key plainly names has a visible cause. Revoking is an update rather than a delete, so a later call is told revoked_api_key instead of simply failing to authenticate. Rotating keeps everything about the key except the secret: the id, the scopes, the send scope and the request history carry on, the old secret dies the instant the new one is minted, and a key holding keys:write can rotate itself over the API. The MCP server lists keys and reads their logs for anyone whose role may see them.
- Inline attachments go as base64 under a 10 MB total cap, and a larger file is uploaded first with POST /files, up to 100 MB, then named by its id, which travels as a download link.
Google Workspace
Fastmail