API Keys

Create an API key

Requires scope: manage. Creates a new API key. The plaintext key is returned ONCE in this response and never again. Closed to apps connected by sign-in (403 connected_app_not_allowed): use the dashboard, an API key or the mails CLI.

post/v1/api-keys

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/api-keys
  • Auth: HTTP bearer

Request body

namestring

A label for the key, 1 to 80 characters, returned as name wherever the key is listed. It need not be unique; left out, name is null.

agent_idstring

Tie the key to one agent. Such a key reads and acts on that agent's mail only: another agent's message, thread, draft, attachment or raw email answers 404, as if it did not exist; lists and search hold its own agent's mail; naming another agent in a filter is a 403. Webhooks and labels belong to the whole workspace, so it cannot create, change, delete, test or replay a webhook, redeliver an event, or create, rename or delete a label (403). Nor can it create an agent, change its own agent's domain lists or send limits, read the request log, the workspace's usage or the send-anyway list, add or revoke a send-anyway entry, revoke an API key, open billing, or add, verify or remove a domain (403), and another agent answers 404 to a change; its reputation and suppressed-recipient reads hold its own agent. The keys it makes are tied to the same agent. Leave it out for a key that reaches every agent.

scopesstring[]

send sends mail, read reads it, and draft writes drafts but can neither send nor schedule one. manage changes the workspace: it creates, changes and archives agents; creates and revokes API keys; creates, changes, tests and deletes webhooks and rotates their secrets; replays webhook deliveries and redelivers events; creates, renames and deletes labels; adds, verifies and removes domains; adds and removes send-anyway entries; opens the billing portal; lists and revokes connected apps; changes and deletes threads and drafts; and cancels and reschedules scheduled messages (rescheduling needs send too).

mode'live' | 'test'

live makes an mk_live_… key that sends real mail, and test an mk_test_… key whose sends are stored and raise events but are never transmitted or billed. A test key can only make test keys.

expires_atstring date-time

When the key stops working: an ISO 8601 UTC time ending in Z. From then on it answers 401 expired_api_key; left out, the key never expires. A key that expires can only make keys that expire no later than it does.

Response

The created key, including the one-time plaintext value.

idstring required

API key id (key_…); DELETE /v1/api-keys/{id} revokes the key.

keystring required

The full plaintext API key. SHOWN ONCE — store it now; it cannot be retrieved again.

prefixstring required

The first 12 characters of key: how the key is shown in lists once key is gone.

mode'live' | 'test' required

The key's mode: live unless the request asked for test. A test key's sends are never transmitted or billed.

scopesstring[] required

The scopes the key holds: those requested, or send and read when none were.

agent_idstring nullable

The agent the key is tied to, or null for a key that reaches every agent.

namestring nullable

The name given in the request, or null.

expires_atstring nullable

When the key stops working, as given in the request. Null for a key that never expires.

created_atstring required

When the key was created.

Changes

No recorded changes to this operation across all 1 revision of this API.