Skip to Content
Alienmail Docs

Authentication

API keys, roles, and the permission each endpoint needs.

Every request needs an API key, sent as a Bearer token in the Authorization header:

curl "https://app.alienmail.io/api/v1/campaigns" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"

There is no sign-in step and no token to refresh: send the key itself on each request.

API keys

Create keys in Workspace settings → Integrations, under API keys. Each key has:

  • A name, so you know which system uses it. Names are unique in a workspace.
  • A role, which decides what the key may do.

The full key is shown once, when it is created. Alienmail keeps only a hash, so a lost key can't be shown again: create a new one and delete the old one. The key list shows when each key was last used. A workspace can create up to 10 keys a day.

A key belongs to one workspace. It only sees and changes that workspace's campaigns, leads and mailboxes, which is why API paths have no workspace id. To work with several workspaces, create a key in each.

Keep keys secret

A key acts for your workspace. Store it in your server's secrets, never in browser or mobile code, and delete it right away if it leaks.

Roles and permissions

When you create a key you pick its role:

RoleWhat the key can do
Read-Only API KeyRead: list campaigns, leads and mailboxes.
Write Access KeyEverything in this API: read, start and pause campaigns, add, update and remove leads, update mailboxes.

A role is a set of permissions, and each endpoint needs one of them. A request to an endpoint whose permission the role lacks gets 403 forbidden, and the message names the missing permission.

PermissionEndpointsRead-OnlyWrite Access
CAMPAIGN_READList campaigns, List leadsYesYes
CAMPAIGN_STARTStart or resume a campaignNoYes
CAMPAIGN_STATUS_UPDATEPause a campaignNoYes
LEAD_CAMPAIGN_ENROLLAdd leads, Update a lead, Remove a lead, Remove leadsNoYes
SMTP_READList mailboxesYesYes
SMTP_UPDATEUpdate a mailboxNoYes

Pick the role with the least access that covers what your integration does: a dashboard that only reads needs Read-Only, a CRM sync needs Write Access.

When a key stops working

A key answers 401 unauthorized when:

  • it was deleted (revoked) in Workspace settings → Integrations;
  • the person who created it left the workspace, or their account was deleted or suspended;
  • the workspace was archived or deleted.

The answer is the same for all of them, and for a key that never existed.

Errors

StatusCodeWhy
401unauthorizedThe Authorization header is missing or not Bearer <key>, or the key doesn't work (see above).
403forbiddenThe key's role lacks the permission the endpoint needs.
429rate_limitedToo many requests with this key. See Rate limits.
{ "error": { "code": "forbidden", "message": "This API key's role does not allow this request. It needs the CAMPAIGN_START permission." } }

The Alienmail MCP server uses the same keys

The Alienmail MCP server accepts the same API keys, with the same roles. AI tools that support OAuth can instead sign in with your Alienmail account and act in one workspace with your role, without a key (see Connect by signing in). To build that sign-in into your own app, see Connect your own app.

OAuth is for the MCP server only. The REST API on this site takes API keys.

On this page