API keys
Create and manage the keys that authenticate programmatic access to your workspace.
API keys let tools outside MailMoo act on your workspace. The same key authenticates both the REST API and the MCP server.
Every key has three things you choose when you create it: a name, an expiry, and a set of permissions.
Creating a key
Keys belong to a workspace, not to you personally. Open Workspace → Members, find Workspace API keys, and create one. Only workspace admins and owners can.
The full key is shown once, at creation. MailMoo stores only a hash of it, so it cannot be shown again. Copy it into your password manager or secret store before closing the dialog. If you lose it, delete the key and create another.
Keys look like sk_live_ followed by a long random string. The list in settings
shows only the prefix, which is enough to tell keys apart.
Permissions
A key can only do what you grant it. Permissions are grouped by area, and each one is either a read or an action:
| Permission | What it allows |
|---|---|
| Read campaigns | View campaigns, their sequences, and their settings |
| Read leads | View lead records, their fields, and their activity |
| Read analytics | View campaign performance, score breakdowns, and tag splits |
| Read CRM | View pipeline stages and tags on leads |
| Read inbox | Read conversations with leads, and read posts, their comments and reactions, and the people who engaged |
| Write campaigns | Create and edit campaigns and their sequence steps. Does not allow starting them |
| Turn on campaigns | Start or pause a sequence |
| Send messages | Send direct messages to leads |
| Send emails | Send emails to leads |
| Move between stages | Move leads from one pipeline stage to another |
| Change tags | Add tags to leads and remove them |
| Manage notes | Write notes on a lead's timeline, and edit or delete them |
| Manage tasks | Create tasks against a lead, and update, complete, or delete them |
The ones that sit indented under an area are granted individually rather than coming along with that area's write access. That is deliberate.
- Send messages and Send emails reach a real person and cannot be undone. They are separate from each other, so a key that answers social messages cannot silently also send email.
- Turn on campaigns is separate from Write campaigns. Building a campaign and putting it in front of hundreds of prospects are different decisions, and this is the boundary that keeps them apart.
- The four CRM writes are separate from each other. Recording what you learned about a lead and moving that lead down the pipeline are different decisions too, so an integration that only adds notes never needs the ability to reclassify your deals.
Credits have no permission of their own. An endpoint that needs them, such as enrichment, spends them as part of doing its work.
New keys default to read-only. Grant the minimum an integration needs, then add more if something fails.
Changing permissions later
You can edit an existing key's permissions at any time from the Edit permissions menu on the key. The key value does not change, so nothing using it needs updating.
This is the easiest way to arrive at a minimal set: start narrow, run your integration, and add whatever it turns out to need. It also means you can revoke one permission immediately if something is behaving unexpectedly, without taking the whole integration down.
Permission changes are recorded against the key, including who made them and when.
Expiry
Every key expires. You choose how long when you create it: 7 days, 1 month, 6 months, or 1 year. One year is the maximum, and there is no "never" option.
This is deliberate. The most common cause of a leaked credential doing damage is that nobody remembered it existed. A key with an end date stops being a risk on its own.
Keys cannot be extended. When one is close to expiring, create a replacement and switch over.
We email the key's owner 30 days, 14 days and 7 days before a key expires, and once more after it has expired. Very short-lived keys may only get the final notice, since there is not much runway to warn about.
The expiry date and remaining days are shown next to each key in settings, so you can see what is coming up without waiting for an email.
Using a key
Send it as a bearer token on every request:
Authorization: Bearer sk_live_YOUR_KEYThe most useful thing to point a key at today is the MCP server, which exposes MailMoo as a set of tools your AI assistant can call directly.
If a request fails with a permission error, the response says which permission was missing. Add it from Edit permissions and try again.
What a key can never do
Regardless of its permissions, a key is scoped to the workspace it was created in and cannot manage billing, change workspace settings, invite or remove people, or create other API keys. Those stay signed-in actions.
A key also inherits the workspace access of the person who created it. If that person's access to the workspace is removed, treat any keys they created as needing replacement.
Keeping keys safe
- Never put a key in client-side code. Anything running in a browser or a mobile app is readable by the user, and a leaked key is usable by anyone.
- Never commit keys to source control. Use environment variables or your platform's secret store.
- Use one key per integration. If something is compromised, or you stop using a tool, you can delete that one key without breaking everything else.
- Grant the least you can. A read-only key that leaks is a much smaller problem than one that can send messages.
- Delete keys you no longer use. An unused key is only a risk.
Replacing a key
There is no in-place rotation. Create the new key first, update whatever uses it, confirm the integration still works, and only then delete the old one. Doing it in that order avoids downtime.
If you only need to change what a key is allowed to do, edit its permissions instead. Replacing it is for a key that has expired, leaked, or belongs to someone who has left.