API keys

API keys authenticate your requests to the REST API, your SMTP connections and API-key sessions on the MCP server. This page explains the two key scopes, how to create and manage keys, and how to store and rotate them safely.

How API keys work

• Each key belongs to one workspace. Everything you do with it happens in that workspace.
• New keys start with secret_ followed by 32 letters and digits, for example secret_••••••••. Keys created before the prefix was introduced keep working.
• Emailit shows the full key once, when you create or regenerate it. Copy it then; you can’t view it again.
• You send the key as a bearer token: Authorization: Bearer secret_…. For SMTP, the key is the password.

Scopes

Every key has one of two scopes. You choose the scope when you create the key.

A Sending Only key that calls any other endpoint gets 403 with a message such as Permission denied: read. Use Full Access keys for back-office jobs that manage resources, and Sending Only keys for anything that only needs to send.

Restrict a key to one domain

When you create a Sending Only key you can pick one verified sending domain. The key can then only send from addresses on that domain:

• Over the API, sending from another domain returns 403 with "error": "Domain not authorized".
• Over SMTP, the message is rejected after DATA with 530 API key is restricted to sending domain: ….

Restricted keys are a good fit for per-app or per-customer credentials, and for keys you have to hand to third-party software such as a CMS plugin.

Before you begin

• You need the Admin role in the workspace to create, edit, regenerate or delete keys. Members can see the list of keys but not change it. See Members and roles.
• To send with a key, you need at least one verified sending domain.

Create an API key

curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'

{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}

Use the key

Pass the key in the Authorization header of every API request:

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

To send over SMTP, use the key as the password:

See SMTP settings for every option.

Manage keys

Open a key from Email API›API Keys to see its scope, domain, Created date and Last used time, and the SMTP settings to use with it.

Last used updates whenever the key authenticates an API request or an SMTP login. A key that has never been used shows Never. In the API, endpoints that take a key ID also accept the key’s name.

Store keys safely

• Keep keys on the server. Never put a key in browser JavaScript, a mobile app, a public repository or a support ticket. Anyone with the key can send email as you and spend your credits.
• Use environment variables or a secrets manager. Load the key at runtime, for example from EMAILIT_API_KEY. Add .env files to .gitignore.
• Give each app and environment its own key. Separate keys for production, staging and each third-party tool make it easy to see who sent what and to revoke one without touching the others.
• Use the narrowest scope. If an app only sends email, give it a Sending Only key, restricted to its domain where possible.
• Watch usage. Email API›Logs lists API and SMTP requests per key, and you can filter Email API›Emails by API key. See Request logs.
• Act fast on a leak. If a key is exposed, regenerate or delete it right away, then check the logs for unexpected sends.

Rotate a key without downtime

Regenerating a key cuts off the old secret at once, so use it only when a key is compromised. For planned rotation, run the old and new keys side by side:

1. Create a new key. Add a key with the same scope and domain restriction as the one you’re replacing. Give it a name that shows the date, such as production-web-2026-10.

2. Deploy the new key. Update the secret in your secrets manager or environment and roll it out to every server, worker and scheduled job that uses the old key.

3. Confirm the switch. Open the new key and check that Last used is recent. In Email API›Logs, filter by the old key and check that requests have stopped.

4. Delete the old key. When the old key’s Last used time no longer changes, delete it.

Troubleshooting

Related