Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

API keys

Create API keys with full or sending-only access, limit them to a domain or an inbox, and manage them.

An API key is the secret your code sends with every request. Create one under API keys in the dashboard, or with the API itself. A key is shown once, when you create it, so store it in your secret manager.

curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "ada@example.com",
    "subject": "Hi",
    "text": "Hello."
  }'

Keys start with bs_. BillionSend stores only a hash of the key, so a lost key cannot be shown again: revoke it and create a new one.

Create a key

In the dashboard, open API keys and choose Create API key. Owners, admins and developers can do it; see team roles. Pick:

  • Name: 1 to 80 characters, so you can tell keys apart. You can rename it later.
  • Permission: Full access or Sending only.
  • Domain: Any domain, or one verified domain of your team.
  • Restrict to an inbox (shown once you have inboxes): the one inbox the key is limited to.

With the API:

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'

The answer is { "id": "…", "token": "bs_…" }: the token appears only here. GET /api-keys lists active keys (never their tokens), and DELETE /api-keys/{id} revokes one at once; requests using it fail immediately.

Permission

Permission Can
Full access Use every endpoint: sending, contacts, segments, topics, broadcasts, domains, webhooks, templates, received mail and API keys. A key limited to one domain reaches only part of that.
Sending only Send emails (POST /emails, POST /emails/batch) and nothing else. Everything outside sending, and every read of stored mail, answers 403 restricted_api_key.

Use a sending-only key in the app that sends transactional mail. A leaked sending-only key cannot read your contacts, change your domains or create other keys.

Limit a key to a domain

A key limited to a domain works inside that one domain and reaches nothing that belongs to the whole team. A domain must be verified before you can limit a key to it; the shared inbox subdomain cannot be used.

What What the key can do
Sending, emails, received mail, inboxes, unsubscribes, broadcasts Only that domain’s. A request for another domain answers 403 restricted_api_key.
GET /emails/metrics Reads that domain’s numbers only; naming another domain in domain_id answers 403 restricted_api_key.
GET /domains and /domains/{id} (read, change, delete, verify) Lists and touches only its own domain. Any other domain, the shared subdomain included, answers 404.
/api-keys POST creates keys limited to the same domain. GET lists, and DELETE revokes, only keys limited to that domain; any other key answers 404.
Contacts, segments, topics Allowed. Contacts are the team’s shared address book, but the key cannot lift a team-wide unsubscribe. A segment or topic it creates is bound to its own domain, and it cannot unbind one.
Webhooks (every method, the signing secret included), suppressions, templates, contact properties, GET /usage, GET /deliverability, verifications and POST /domains 403 restricted_api_key: these belong to the whole team.

Use one for a service that belongs to a single brand: if it leaks, it reaches that brand’s domain and nothing else, not your webhooks, your other keys or your other domains.

Limit a key to an inbox

An inbox key gives an AI agent access to one inbox and nothing else. It needs full access, cannot also be limited to a domain, and can read, reply, forward and send drafts only for that inbox, and send only from its address. It stops working when the inbox expires or is deleted.

Limits

Limit Value
Active keys per team 25, SMTP credentials included. Revoke one to create another (422 otherwise).
Active keys per inbox 5, outside the team’s 25.
Requests 600 per minute per key and 3,000 per team; see API basics.

Who can create which key

  • In the dashboard, owners, admins and developers create keys.
  • A key you create with the API is never broader than the key that created it: a sending-only key can only create sending-only keys, a key limited to a domain can only create keys for that domain (and sees and revokes only those), and an inbox key cannot create keys.
  • A key acts with the team role its creator has today, checked on every request. The creator is the person who made it in the dashboard (or connected the app that made it); a key made through the API carries the creator of the key that made it. Role does not narrow everyday work: a full-access key sends and manages contacts, broadcasts, domains, webhooks and keys whichever role its creator has (a key limited to one domain is the exception, see above). The high-risk acts (erasing a recipient, removing a suppression, taking back an unsubscribe) need a key whose creator is an owner or admin right now; other keys answer 403 forbidden. If the creator is demoted, their keys follow the new role from the next request. If they are removed from the team or leave, every API key they made, the keys those keys made and their agent keys stop working at once (401 invalid_api_key) and show as revoked; being invited back does not bring them back. See team roles.

Creating, renaming and revoking a key are recorded in the audit log.

Other keys

  • SMTP credentials are sending-only keys created on the SMTP page for the SMTP relay.
  • Agent keys (bs_agent_…) are for the MCP server only. They are created under MCP, are limited to read-only, read and reply, or read and send, and a team holds up to 20. Your regular API keys do not work on the MCP server.

Was this page helpful?