Markdown

API keys

Manage Groundmail API keys from the public API (Bearer auth with a full-scope credential) or the dashboard (API keys).

Updated Nov 17, 20263 min read

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:send
Read only emails:read, domains:read, account:read

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 tenant on the send; naming a different tenant gets 403 forbidden.
  • It sees and manages only that tenant's emails, domains and suppressions.
  • It can read its own tenant: GET /tenants/{tenant}, /stats and /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:read can only read, mailboxes:write can also label and mark mail, and mailboxes:send can 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

GET/api-keys?limit=25&cursor=…
JSON
{
  "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

POST/api-keys

Add "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):

JSON
{ "name": "Agent", "scopes": ["emails:send"], "allowed_domains": ["yourdomain.com"] }
JSON
{
  "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

TypeScript
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)
Terminal
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>

Was this page helpful?