Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Groundmail API Keys API
version: 0.16.0
description: 'Transactional email API for developers.
Auth: `Authorization: Bearer gm_…` with an API key, or `Bearer gm_oat_…` with an OAuth
access token from the device flow (`groundmail login`). Dashboard session cookies work
for integrations.
Azure managed identity (keyless): an Azure workload can send a Microsoft Entra access
token (a JWT) as the Bearer credential instead of a key. Register the identity''s tenant
ID, object ID and token audience in the dashboard (API keys → Azure managed identity);
it then has the same access options as an API key (scopes, domain limit, tenant).
App-only tokens only. Any authentication failure is the same 401 `unauthorized`.
See https://docs.groundmail.dev/authentication/azure-managed-identity.
Test mode: a test key (`gm_test_…`, `POST /api-keys` with `test: true`) behaves
like a live key, but its sends are never delivered: they are stored with
`test: true`, get simulated events and webhooks (`data.test: true`), and do not
count toward plan limits, the sending ramp, stats or billing. Simulator
addresses (`delivered@`, `bounce@`, `block@`, `complaint@`, `suppressed@`,
`delayed@simulator.groundmail.dev`, plus addressing allowed) produce one outcome
each with any key. See https://docs.groundmail.dev/testing.
Tenants: a platform that sends email for its own customers creates one tenant per
customer (`/tenants`), each with its own domains, suppression list, stats, sending
ramp and pause switch. Name the tenant with `tenant` on sends, domains and
suppressions, or send from a domain the tenant owns. API keys and webhook
endpoints can be limited to tenants. Included on pay as you go and the Dedicated plan;
elsewhere a request that names a tenant gets 403 `tenants_not_enabled`. See
https://docs.groundmail.dev/tenants.
Data retention: sent emails (content and events) and received emails are kept for
your plan''s window, then deleted: 7 days on Free, 30 on Pro, 90 on Scale, up to 365
on Dedicated. Past it, `GET /emails/{id}` and `GET /received-emails/{id}` return
404 `not_found` and lists no longer include them. Aggregate stats
(`GET /deliverability`) are kept. Store webhook events to keep history longer. See
https://docs.groundmail.dev/emails#data-retention.
Scopes: every credential carries scopes (`full`, `emails:send`, `emails:read`,
`domains:read`, `domains:write`, `webhooks:write`, `templates:write`,
`suppressions:write`, `account:read`). Each operation lists the scope it needs under
`x-required-scope` (space-separated: all of them; `a | b`: either); a credential
without it gets 403 `insufficient_scope` with `required_scope`. `full` grants everything; `domains:write` includes `domains:read`.
Legacy `sending` API keys have `emails:send` + `emails:read`.
Production base URL: https://api.groundmail.dev'
servers:
- url: https://api.groundmail.dev
description: Production
tags:
- name: API Keys
description: Manage API keys (list, create, revoke)
paths:
/api-keys:
get:
operationId: listApiKeys
x-required-scope: full
summary: List API keys
tags:
- API Keys
security:
- bearerAuth: []
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
description: Maximum number of API keys to return (1–100)
- name: cursor
in: query
schema:
type: string
description: Opaque cursor for the next page
responses:
'200':
description: API key list
content:
application/json:
schema:
$ref: '#/components/schemas/ListApiKeysResponse'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
operationId: createApiKey
x-required-scope: full
summary: Create an API key
tags:
- API Keys
security:
- bearerAuth: []
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyRequest'
responses:
'200':
description: API key created (token shown once)
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyResponse'
'400':
description: Invalid field
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: '`tenant` set on an account without tenants (`tenants_not_enabled`)'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The `tenant` does not exist
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api-keys/{id}:
delete:
operationId: deleteApiKey
x-required-scope: full
summary: Revoke an API key
tags:
- API Keys
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: API key revoked
content:
application/json:
schema:
type: object
required:
- ok
properties:
ok:
type: boolean
enum:
- true
'401':
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: API key not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ListApiKeysResponse:
type: object
required:
- data
- has_more
- next_cursor
properties:
data:
type: array
items:
$ref: '#/components/schemas/ApiKey'
has_more:
type: boolean
next_cursor:
type: string
nullable: true
ErrorResponse:
type: object
required:
- error
properties:
error:
type: object
required:
- message
properties:
message:
type: string
description: What went wrong, in plain English. Wording can change; branch on `code`.
code:
$ref: '#/components/schemas/ErrorCode'
hint:
type: string
description: 'How to fix the error. Specific to the failure when known (for example a sandbox recipient), otherwise the default for `code`.
'
docs_url:
type: string
format: uri
description: Link to this code on the errors page, `https://docs.groundmail.dev/errors#<code>`.
example: https://docs.groundmail.dev/errors#validation_error
upgrade_url:
type: string
description: 'Dashboard path to upgrade when code is plan_limit or domain_limit. Absent for `daily_ramp_limit`, which upgrading does not lift.
'
required_scope:
type: string
description: 'With `insufficient_scope`: the scope (or space-separated scopes) the operation needs. Also sent as `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`.
'
details:
description: 'Optional structured details. For send blocks this may include `suppressed` (global suppression list) or `category_unsubscribed` plus `category` and `email_id` (category opt-out). A `daily_ramp_limit` carries `stream` (`transactional` or `product`), `daily_limit` (today''s recipient limit for that stream), `used_today`, `recipients` (in this send), `ramp_stage` and `resets_at` (next 00:00 UTC, ISO 8601), plus `tenant` when the tenant''s own limit refused the send.
'
CreateApiKeyResponse:
type: object
required:
- id
- name
- scope
- scopes
- allowed_domains
- prefix
- token
- created_at
properties:
id:
type: string
name:
type: string
scope:
type: string
enum:
- full
- sending
scopes:
type: array
items:
$ref: '#/components/schemas/ApiScope'
allowed_domains:
type: array
items:
type: string
test:
type: boolean
description: A test key (`gm_test_…`).
tenant:
type: string
description: The tenant this key is limited to (`external_id`). Present only on tenant keys.
prefix:
type: string
token:
type: string
description: Full API key (`gm_…`, or `gm_test_…` for a test key), shown once at creation
created_at:
type: string
format: date-time
ApiKey:
type: object
required:
- id
- name
- scope
- scopes
- allowed_domains
- prefix
- created_at
properties:
id:
type: string
name:
type: string
scope:
type: string
enum:
- full
- sending
description: Legacy label; `sending` for any key narrower than full.
scopes:
type: array
items:
$ref: '#/components/schemas/ApiScope'
allowed_domains:
type: array
items:
type: string
description: Domains this key may send from; empty means any verified domain.
test:
type: boolean
description: A test key (`gm_test_…`). Its sends are simulated and never delivered.
tenant:
type: string
description: The `external_id` of the tenant this key is limited to. Present only on tenant keys.
prefix:
type: string
description: Visible key prefix (e.g. `gm_1a2b3c4d`, or `gm_test_1a2b3c4d` for a test key)
created_at:
type: string
format: date-time
last_used_at:
type: string
format: date-time
nullable: true
ErrorCode:
type: string
description: 'Stable, machine-readable error code. Each code is documented at
`https://docs.groundmail.dev/errors#<code>`. New codes may be added;
existing codes keep their meaning.
- `validation_error` (400, 422): the request failed validation, or every recipient is suppressed or opted out (422). Fix the field named in `message`/`details`.
- `unauthorized` (401): missing, malformed or revoked API key. Send `Authorization: Bearer gm_…`.
- `forbidden` (403): the key is valid but the action is not allowed (unverified `from` domain, sandbox send to someone other than the account email, no payment method on file, sending restricted).
- `insufficient_scope` (403): the API key''s scope does not cover this endpoint.
- `domain_not_allowed` (403): the API key is limited to other sending domains than the one in `from`, or `from` is on another tenant''s domain.
- `tenants_not_enabled` (403): the request names a tenant, but tenants are not enabled for this account. They are included on pay as you go and the Dedicated plan.
- `newsletter_not_enabled` (403): the send uses `category: "newsletter"`, but newsletter sending isn''t enabled on this account. Newsletter email is accepted only for approved accounts.
- `not_found` (404): no resource with that id for this team.
- `conflict` (409): the resource already exists or its state blocks the change.
- `plan_limit` (429): the plan''s monthly or daily sending limit was reached. See `upgrade_url`.
- `daily_ramp_limit` (429): the send would go over a new account''s daily ramp-up limit for its stream, or its tenant''s own ramp or daily limit (`details.tenant`). Upgrading does not lift it; wait for `details.resets_at`.
- `domain_limit` (403): the plan''s domain limit was reached. See `upgrade_url`.
- `idempotency_conflict` (409): the `Idempotency-Key` was reused with a different body, or the first request is still running.
- `rate_limited` (429): too many requests. Wait `Retry-After` seconds.
- `timeout` (408): a long-poll (GET /test-inbox/wait) ended before a matching email arrived. Safe to call again.
- `upstream_error` (502, 503, 504, or a passed-through 4xx): the mail server did not accept the request. 502/503 are safe to retry with the same `Idempotency-Key`; 504 means the outcome is unknown.
- `not_configured` (503): the feature is temporarily unavailable.
- `internal_error` (500): unexpected server error. Retry with backoff.
'
enum:
- validation_error
- unauthorized
- forbidden
- insufficient_scope
- not_found
- conflict
- plan_limit
- daily_ramp_limit
- domain_limit
- idempotency_conflict
- rate_limited
- timeout
- upstream_error
- not_configured
- internal_error
- domain_not_allowed
- tenants_not_enabled
- newsletter_not_enabled
ApiScope:
type: string
description: A scope for API keys and OAuth tokens. `full` grants everything.
enum:
- full
- emails:send
- emails:read
- domains:read
- domains:write
- webhooks:write
- templates:write
- suppressions:write
- account:read
CreateApiKeyRequest:
type: object
properties:
name:
type: string
scopes:
type: array
items:
$ref: '#/components/schemas/ApiScope'
description: 'What the key may do, e.g. `["emails:send"]` (send only) or `["emails:read", "domains:read", "account:read"]` (read only). Takes precedence over `scope`.
'
allowed_domains:
type: array
items:
type: string
description: 'Verified domains the key may send from. Needs `emails:send` and cannot be combined with `full`. Sends from other domains get 403 `domain_not_allowed`.
'
scope:
type: string
enum:
- full
- sending
default: full
description: Legacy. `sending` means `emails:send` + `emails:read`.
test:
type: boolean
default: false
description: 'Create a test key (`gm_test_…`). It has the same scopes and checks as a live key, but its sends are never delivered: they get simulated events and webhooks and do not count toward plan limits, the sending ramp, stats or billing.
'
tenant:
type: string
description: 'Limit the key to one tenant (its `external_id` or `id`). The key sends only as that tenant (naming another gets 403 `forbidden`), sees and manages only that tenant''s emails, domains and suppressions, and can read its own tenant (`GET /tenants/{id}`, `/stats`, `/domains`). Every other endpoint (webhooks, templates, received email, deliverability, events, API keys, other tenants, account settings) answers 403 `forbidden`. With a tenant, `allowed_domains` may be combined with `full`. Deleting the tenant revokes its keys.
'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Groundmail API key (`gm_…`), OAuth access token (`gm_oat_…`), or a Microsoft Entra access token from an Azure managed identity registered in the dashboard (keyless; see https://docs.groundmail.dev/authentication/azure-managed-identity). All carry scopes; see the API description.
'