API and MCP

Create an API key

Q: Can a key add workspaces?

Yes. An admin key created on the paying workspace can add one with POST /workspaces or the create_workspace tool, and rename one with PATCH /workspaces/{id}. The same rules apply as in the dashboard: the plan must be active, no workspace on the bill can be restricted, and a bill holds at most 25 workspaces. The paying workspace's owners and admins get access to the new one.

How to create an EmailPal API key, pick its scope, why we only show it once, how to use it with REST and MCP, and how one key can work across every workspace on your bill.

Create

Sign in → API keys.
Name the key and pick a scope (below).
Create it and copy the ep_live_… secret immediately.
We store a hash. If you lose it, create another and revoke the old one.

REST: Authorization: Bearer ep_live_… against https://www.emailpal.io/api/public/v1.

MCP: EMAILPAL_API_KEY in the server env. See Connect the MCP server.

Pick a scope

Scopes are hierarchical: admin includes write, which includes read.

Scope	What it allows
Read	Read anything on the account: domains, mailboxes, warming, the inbox, campaigns, leads, replies and the pipeline. It cannot change or spend anything.
Write	Create and change domains, mailboxes, warming, mail, campaigns, leads and CRM records. This includes launching and resuming campaigns, which sends real email.
Admin	Adds exporting mailbox passwords and topping up the domain balance.

Give a reporting script or a monitoring agent a read key. Give a provisioning or campaign-running script a write key. Keep admin for the one thing that needs credentials or the balance.

Keys and workspaces

A key belongs to the workspace you create it in, and acts on that workspace by default.

If you run several workspaces on one bill, create the key on the workspace that pays (the one whose plan the others share). That key can then act on any workspace billed to it:

On REST, send the workspace's id in an X-Workspace-Id header. A workspace_id query parameter works too, for tools that cannot set headers.
On MCP, pass workspace_id to any tool, or set EMAILPAL_WORKSPACE_ID to choose a default.
GET /workspaces, or the list_workspaces tool, lists the ids the key can use.

A key created on a workspace that someone else pays for only ever reaches that workspace. Asking it for another one returns 404 workspace_not_found, the same answer as for a workspace that does not exist.

The key's scope and hourly request budget stay the same whichever workspace it acts on. Changes are recorded in the audit log of the workspace that was changed.

FAQs

Can I have multiple keys?

Yes. Revoke any key you pasted into a ticket, a screenshot or a chat log.

Does a key see every account I belong to?

A key sees the workspace it was created in. A key created on the paying workspace can also reach every workspace billed to it, one request at a time, by naming the workspace (see Keys and workspaces). It never reaches workspaces on another bill. Do not share keys across customers: if a client should only see their own workspace, create the key inside that workspace.

Can a key add workspaces?

Yes. An admin key created on the paying workspace can add one with POST /workspaces or the create_workspace tool, and rename one with PATCH /workspaces/{id}. The same rules apply as in the dashboard: the plan must be active, no workspace on the bill can be restricted, and a bill holds at most 25 workspaces. The paying workspace's owners and admins get access to the new one.

Does a key cost extra, or does it need a certain plan?

No. API keys are included on every plan. Each plan has an hourly request budget, which the docs describe.

Need More Help?

MCP server and REST API.