API basics

Authentication & API keys

One key, two scopes. Log in from the CLI with a click, or create keys in the dashboard — scoped to one project or your whole account.

View as Markdown ↗

How access is organized

Your account contains workspaces (the billing boundary — one plan, one bill), and each workspace contains projects (where contacts, campaigns, sending domains, and keys live). Roles are per project: Owners and Admins can create keys there.

One key, two scopes

There is one kind of key (ebk_). When you create it you choose its scope — that's the whole model.

One projectThe key is bound to a single project: it sends email, reads and writes that project's contacts, campaigns and lists, and manages that project's sending domains at /v1/domains. Nothing outside the project. This is the key for your application.All accessThe key acts as you across your whole account: it provisions workspaces, projects, and domains through the account API, and can act in any project you admin by naming it per call. For agents and CLIs.

The same key is also your SMTP password — there is no separate SMTP credential to manage, and revoking a key stops both at once. A project key is the easier one to point an SMTP client at, because an all-access key has to say which project it means.

Browser login (CLI & MCP)

The easiest way to get a key is not to copy one at all. In a terminal:

Terminal

emailbump login

Your browser opens with a pairing code — click Authorize and choose the scope (one project, or all access). Approval alone does not create a key: the CLI must claim the approved request before it expires. Only one poll can receive the credential. If login is interrupted before it receives the key, start login again.

The CLI stores the credential in ~/.config/emailbump/credentials.json (0600 on Unix); both the CLI and MCP server use it automatically. Run emailbump login again to switch project or scope. emailbump logout only removes the local credential; it does not revoke the key. Revoke it in Developers → API Keys if needed. Install the CLI.

What can this key do?

GET /v1/me (emailbump whoami, or the whoami MCP tool) answers it from the server rather than from what's stored locally: which project the key is in, whether the account's email is confirmed, which sending domains are verified, the from address to use, and whether the compliance footer carries your own postal address or our placeholder. This is setup guidance, not a complete permission check: verified-domain readiness can be false while shared-domain testing is allowed, and send-time quota, suspension, consent and abuse checks still apply. GET /v1 needs no key at all and lists the API.

No account yet

An account takes an email address and nothing else — no password, no browser.

From a terminal

emailbump signup --email you@company.com --name "Dana" --accept-terms

Or over HTTP

curl -X POST https://emailbump.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "name": "Dana", "accept_terms": true }'

Both return two keys; the CLI stores the first: a project key for sending, and an account key for creating further workspaces, projects and keys — so nothing in setup needs a browser. Over MCP it's create_account. accept_terms is the person's answer rather than the tool's — creating an account means agreeing to the terms, so ask them first.

There is no password because there needn't be one yet. If they want to sign in to the dashboard later, "Forgot password" sets one on an account that never had one.

Prefer the browser? emailbump signup with no --email opens the authorize page, where "Create an account" sits beside "Log in" — the pairing code survives the detour and the terminal picks up the key. Over MCP that is start_authorization and finish_authorization.

A new account can read the API immediately but can't send until the email address is verified. The verification email carries a link and a six-character code, so nobody has to leave the terminal:

cURL

emailbump verify-email --email you@company.com PL8FJD

Ask, don't fetch

Over MCP that's verify_email_code. The person reads the code out of their own inbox. Only use a programmatic mailbox when its owner has explicitly authorized that access.

Create a key in the dashboard

01
Open API keys
Go to Developers → API Keys. An administrator or owner can create credentials.
02
Name the key
Use a name that identifies the service and environment, such as checkout-production. The name appears next to every request the key makes.
03
Choose an expiry (optional)
Leave it as Never, or pick 30 / 90 / 365 days. After that the key stops working.
04
Store the secret
Copy the full ebk_ value immediately. Email Bump only shows it once.

Authenticate

Send the key in the HTTP Authorization header using the Bearer scheme — same header for both scopes.

HTTP

Authorization: Bearer ebk_your_key

Act in a project (all access)

A project-scoped key already knows its project. An all-access key doesn't — with exactly one project it is selected automatically, and with several you name it per call (allowed only where you are an Admin). If you forget, the error lists your projects:

HTTP

X-Project-Id: <project-uuid>

In the CLI that's --project <uuid> (or EMAILBUMP_PROJECT); MCP tools take an optional project_id. Find project ids with emailbump workspaces:list. Account endpoints — workspaces, projects, domains — need no project, because they say which one in the path.

Set an expiry

Choose Never, 30, 90 or 365 days when creating a key in Developers → API Keys. The session-authenticated dashboard key endpoints accept expires_in_days. The public all-access endpoint POST /v1/projects/{id}/api-keys currently accepts a name only and creates a key without expiry; do not send an expiry there expecting it to be enforced.

The key list shows an Expires column and marks a key Expired once the date passes. Rotate or replace it before then to avoid interrupted sends.

Rotate a key

Rotating issues a brand-new secret for the same key in place. The old secret stops working immediately, but the key's name and its request history are preserved — so your activity log stays continuous.

01
Open the key menu
On Developers → API Keys, open the ⋯ menu for the key and choose Rotate key.
02
Copy the new secret
The replacement ebk_ value is shown once. Update your environment variables or secrets manager.

Rotate on a schedule

Rotate production keys periodically, and immediately if a key may have been exposed. Because rotation keeps the same key identity, dashboards and the request log continue to attribute calls to the same name.

Request activity

Open Developers → API logs for requests attributable to the selected project, including failed calls. Rows show method, path, calling key, status and latency; open a request for recorded payload details. A request that cannot be attributed to your project is not shown there. SMTP logs records gateway attempts; Transactional shows submitted messages and delivery events. These are separate from key management under API Keys.

Protect your keys

Keep keys in server-side environment variables or a secrets manager.
Use a separate key for each service and environment.
Never commit keys or include them in browser bundles.
Prefer an expiry, and rotate a key immediately if it may have been exposed.

Revoke a key

Revocation takes effect immediately. Create and deploy the replacement before revoking an active production key to avoid interrupted sends. Rotating is usually better than revoke-and-recreate because it keeps the key's name and history.