API keys

An API key lets your code call the platform API for one organization, with the permissions you choose.

API keys are managed in the dashboard only. The platform API can’t create, rotate or revoke keys, so a leaked key can never create another.

Create a key

Open the create panel

Go to Developers > API Keys and select Create API Key.

Name the key

Enter a Key Name (up to 255 characters) that says where the key will live, such as Production backend. Add a Description (optional) if it helps your team.

Choose an expiration

Pick Never, 30 days, 90 days, 6 months or 1 year. After that date the key stops working.

Set permissions

For each group under Permissions, choose No access, read-only access, or Full access. Full access grants both the read and the write scope for that group. You need at least one.

Restrict IP addresses (optional)

In IP Allowlist (optional), enter the IP addresses allowed to use the key, separated by commas. Leave it empty to allow any address.

Enter individual addresses, such as 203.0.113.10. Each request’s address is compared exactly, so a range such as 203.0.113.0/24 won’t match anything.

Create and copy the secret

Select Create. The panel shows the Key ID and the Secret Key. Copy the secret key now: it’s shown only once. The key ID isn’t secret. Use it to find the key in logs and in the dashboard.

Scopes

There are 18 scopes: a read scope and a write scope for each of nine groups. The dashboard shows the group names and the read-access labels below.

Group	Read scope	Write scope	Covers
Messages	`messages:read` (Read Message Log)	`messages:send` (Send Messages)	The message log. The write scope also lets the key send through the email send API
Contacts	`contacts:read`	`contacts:write`	Contacts, lists, tags, custom fields, segments, imports, exports and suppressions
Campaigns	`campaigns:read`	`campaigns:write`	Campaigns, their content, audiences, schedules and send actions
Templates	`templates:read`	`templates:write`	Message templates
Analytics	`analytics:read` (Read Analytics)	`analytics:write` (Create Report Exports)	Reports, dashboard figures and report exports
Webhooks	`webhooks:read`	`webhooks:write`	Webhook endpoints and their deliveries
Sending Domains	`domains:read`	`domains:write`	Sending domains, IP pools and IP pool requests. Not sending keys or SMTP users
Sender Identities	`senders:read`	`senders:write`	Sender identities and push applications
Mailboxes	`mailboxes:read`	`mailboxes:write`	Mailboxes, aliases and mail domains

How a scope is chosen for a request:

GET requests need the group’s read scope.
POST, PATCH, PUT and DELETE requests need the write scope. That includes action endpoints that only read, such as previewing a campaign or a contact import.

A request without the right scope fails with 403. The response names the missing scope and lists the ones the key has:

{
  "success": false,
  "message": "This API key is missing the contacts:write scope required by this endpoint. Issue a key that carries it to continue.",
  "code": "E_INSUFFICIENT_SCOPE",
  "requiredScope": "contacts:write",
  "grantedScopes": ["contacts:read", "messages:read"]
}

Older keys may hold email:send and email:read. These are the previous names of messages:send and messages:read, and they still work. See the changelog.

The Send Messages permission

A key with Send Messages also works on the email send API, where it can send from any sending domain your organization owns. You can remove the permission from a key later. You can’t add it to an existing key: create a new key instead.

Rate limits

Each key has its own limits, so one busy integration can’t use up another’s budget.

Limit	Default	Where to change it
Requests per minute	300	Settings tab, Rate Limits: 60, 120, 300, 600 or 1,200
Requests per day	No daily cap	Settings tab, Rate Limits: 10,000 to 1,000,000

A request over either limit fails with 429. See Rate limits for the headers and how to retry.

Manage a key

Select a key in Developers > API Keys to open it. It has three tabs:

Tab	What’s there
Overview	Key Information (key ID, the masked key, created, last used, expiry), Permissions, Recent Requests (the last five) and Access Restrictions
Usage	Usage Overview and the full Request Logs
Settings	Key Details, Security (the IP allowlist), Rate Limits, Expiration and the Danger Zone

To change the name, description or IP allowlist, select Edit on Key Information. To change scopes, select Edit on Permissions. To change the expiry, use Expiration on the Settings tab.

Rotate a key

On the Overview tab, select the regenerate icon next to the masked key.
Confirm with Regenerate.
Copy the new secret. It’s shown once.

The old secret stops working immediately. The key keeps its ID, scopes and limits.

For a rotation without downtime, create a second key with the same permissions, deploy it, then revoke the first.

Revoke a key

On the Settings tab, under Danger Zone, select Revoke Key and confirm. Every request using the key fails from then on, including sends through the email send API. You can’t undo this.

Request logs

The Usage tab lists every request made with the key, newest first. Each entry has the Method, Endpoint, Status, Time, IP Address and Timestamp. Filter by method or by status code to find failures. Only requests that authenticated with the key are logged. A request rejected as Unauthorized access never matched the key, so it won’t appear here.

Key statuses

Status	Shown as	Meaning
`active`	Active	The key works
`expired`	Expired	The expiry date has passed. Requests are rejected
`revoked`	Revoked	Someone revoked the key, or the member who created it left the organization

“Unauthorized access”

Why: The key is wrong, revoked or expired, or the request came from an IP address that isn’t on the key’s allowlist.Fix: Check the key’s status and allowlist. If your servers’ addresses change, remove the allowlist or keep it up to date.

“This API key is missing the … scope required by this endpoint”

Why: The key doesn’t have the scope in requiredScope.Fix: Select Edit on the key’s Permissions and add it. For messages:send, create a new key instead.

“The "messages:send" scope cannot be added to an existing API key”

Why: The send API can only receive a key when it’s created or regenerated.Fix: Create a new key with Messages set to Full access.

“This endpoint cannot be accessed with an API key”

Why: Key management, billing, the wallet and a few other areas are dashboard-only.Fix: Do this in the dashboard.

Authentication

How to send the key, and which credential works where.

Sending keys

The separate credential the email send API needs.

Rate limits

Per-key limits, headers and retries.

Errors

Error codes and what to do.

Start here

Sending email

Webhooks

Recipes

Reference

Create a key

Scopes

The Send Messages permission

Rate limits

Manage a key

Rotate a key

Revoke a key

Request logs

Key statuses

Authentication

Sending keys

Rate limits

Errors

​Create a key

​Scopes

​The Send Messages permission

​Rate limits

​Manage a key

​Rotate a key

​Revoke a key

​Request logs

​Key statuses

​Related

Authentication

Sending keys

Rate limits

Errors

Create a key

Scopes

The Send Messages permission

Rate limits

Manage a key

Rotate a key

Revoke a key

Request logs

Key statuses

Related