Authentication
Every request carries your API key in the Authorization header, with the word Bearer and a space in front of it:
curl "https://api.emailchaser.com/r/campaigns" \
-H "Authorization: Bearer run_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"The word Bearer is required
The API reads the key from after the first seven characters of the header, so a key sent without Bearer loses its first characters and comes back 401 Invalid API key format. Tools that ask for a "token" usually add Bearer for you; tools that ask for a raw header value, Postman's header tab included, need you to type it.
A key looks like run_ followed by 8 letters or digits, an underscore and 40 more letters or digits: 53 characters in all. Create one on the API & MCP page, as Start here shows.
A key is either read-only or read and write
When you create a key you choose its Access, and there is nothing in between:
| Access | What it can call |
|---|---|
| Read only | Every GET endpoint, plus four POST endpoints that buy and send nothing: /audience/size, /setup/ping, /dfy/domains/check and /lead-finder/searches |
| Read & write | Every endpoint, including the ones that spend credits, charge your card, order domains and mailboxes, and send email |
Each endpoint in the API reference shows which kind of key it needs. A few endpoints change nothing but still need a read and write key: POST /copilot/plan, POST /autopilot/plan and POST /imports/instantly/accounts.
Give an integration the least it needs. A dashboard or a reporting job only needs Read only; anything that adds leads, launches campaigns or sends replies needs Read & write.
Each key belongs to one workspace
A key sees only its own workspace's campaigns, leads, mailboxes and replies. Agencies usually create one workspace per client and one key per workspace, so a key can be handed over or revoked without touching anyone else.
The key of your main workspace can do a few things other keys can't:
- create workspaces with
POST /workspaces, and list every workspace in the account; - create keys for a child workspace with
POST /workspaces/{id}/api-keys; - add to or remove from the account-wide blocklist;
- read and update the mailboxes of child workspaces.
Every auth error tells you what went wrong
| Status | error message | What to do |
|---|---|---|
| 401 | Missing Authorization header | Send the header on every request. |
| 401 | Invalid Authorization header format | The header is too short. Send Bearer <API key>. |
| 401 | Missing API key | Nothing follows Bearer . Add the key. |
| 401 | Invalid API key format | Check that the header starts with Bearer and the key with run_. |
| 401 | Invalid API key | The key was deleted or paused, or it was copied wrong. |
| 401 | API key expired. Create a new one in Emailchaser: API & MCP in the side menu. | Only keys created by the in-app AI setup expire. Create a new key. |
| 403 | This API key is read-only; this endpoint requires the read_write scope | Use a Read & write key for this call. |
These come back as a JSON body, {"error": "..."}, but with a Content-Type of text/plain. Parse the body as JSON whatever the header says.
Keep your key on the server
Treat a key like a password. Keep it in an environment variable or a secrets manager, never in a browser, a mobile app or a public repository. If a key leaks, delete it on the API & MCP page and create a new one; the old one stops working at once.
Questions about the API? Email support@emailchaser.com.