Base URL: https://api.groundmail.dev
Scopes
Each key has scopes (see Authentication for the full list). The dashboard offers three presets:
| Preset | Scopes |
|---|---|
| Full (default) | full |
| Send only | emails: |
| Read only | emails:, domains:, account: |
Or pick any combination. A key without the scope a request needs gets 403 insufficient_scope.
Limit sending to domains
allowed_domains restricts which verified domains a key can send from (the domain of from). It needs a send scope and cannot be combined with full, since a full key could create an unrestricted one. A send from another domain gets 403 domain_not_allowed.
Test keys
"test": true creates a test key. Its token starts with gm_test_, and it has scopes like any key. Sends with it run every check (validation, templates, suppressions, idempotency, scheduling) and fire webhooks, but nothing is delivered, and they do not count toward plan limits, the ramp-up, stats or billing. Emails and webhook events from it carry test: true. See Testing.
Limit a key to one tenant
"tenant": "cust_8412" limits the key to one of your tenants (its external_id or id). Use it for anything that acts for one customer:
- It sends only as that tenant. It does not need
tenanton the send; naming a different tenant gets 403forbidden. - It sees and manages only that tenant's emails, domains and suppressions.
- It can read its own tenant:
GET /tenants/{tenant},/statsand/domains. - Everything else (webhooks, templates, received email, deliverability, events, API keys, other tenants, account settings) answers 403
forbidden.
Its scopes still apply on top. Since a tenant key cannot create keys, allowed_domains can be combined with full on it. Deleting the tenant revokes its keys. Tenants are on the pay-as-you-go and Dedicated plans; on Free, tenant returns 403 tenants_not_enabled.
Limit a key to mailboxes
"mailbox_ids": ["mbx_…"] limits the key to those mailboxes, up to 100. Use it for a key you give to one agent:
- It works with those mailboxes' mail. Its scopes still apply on top:
mailboxes:readcan only read,mailboxes:writecan also label and mark mail, andmailboxes:sendcan send and reply. - It can't create, change, forward or delete mailboxes.
- Everything else in your account answers 403
forbidden.
The key needs mailboxes:read, mailboxes:write, mailboxes:send or full; the limit holds on a full key too. mailbox_ids can't be combined with allowed_domains. With tenant, the mailboxes must be that tenant's. Keys limited this way list their mailbox_ids. A mailbox that doesn't exist is 404 not_found. If a mailbox is deleted, the key stays limited to the rest and never widens.
Legacy scope
The scope field (full or sending) still works: sending means emails:send + emails:read. Responses keep scope for older clients; it reads sending for any key narrower than full.
Azure managed identity
Azure workloads can skip keys entirely: register a managed identity under API keys → Azure managed identity in the dashboard and call the API with its Microsoft Entra token. An identity has the same access options as a key (Full, Send only, Read only, a domain limit, a tenant) and is listed and revoked on its own, not through these endpoints. See Authenticate from Azure with managed identity.
List
/api-keys?limit=25&cursor=…{
"data": [
{
"id": "…",
"name": "Default",
"scope": "full",
"scopes": ["full"],
"allowed_domains": [],
"test": false,
"prefix": "gm_abcd",
"created_at": "2026-07-26T00:00:00.000Z",
"last_used_at": null
}
],
"has_more": false,
"next_cursor": null
}Create
/api-keysAdd "test": true for a test key (gm_test_…), or "tenant": "cust_8412" for a key limited to one tenant. Keys limited to a tenant carry "tenant" in list and create responses; other keys have no tenant field.
Response (token shown once):
{ "name": "Agent", "scopes": ["emails:send"], "allowed_domains": ["yourdomain.com"] }{
"id": "…",
"name": "Agent",
"scope": "sending",
"scopes": ["emails:send"],
"allowed_domains": ["yourdomain.com"],
"test": false,
"prefix": "gm_…",
"token": "gm_…",
"created_at": "2026-07-26T00:00:00.000Z"
}Delete
DELETE /api-keys/{id} → { "ok": true }
Cannot delete the key authenticating the request.
SDK / CLI
await client.apiKeys.create({ name: 'CI', scope: 'sending' })
await client.apiKeys.create({ name: 'Tests', scopes: ['emails:send', 'emails:read'], test: true })
await client.apiKeys.create({ name: 'Acme', scopes: ['full'], tenant: 'cust_8412' })
await client.apiKeys.list()
await client.apiKeys.remove(id)groundmail keys create --name Agent --scopes emails:send --allowed-domains yourdomain.com
groundmail keys create --name Tests --scopes emails:send,emails:read --test
groundmail keys list
groundmail keys delete --id <id>