Authentication
API keys, the read and write scopes, and the separate permission to send emails.
Every request to https://api.maylee.app/api/v1 carries a Maylee API key as a Bearer token:
curl https://api.maylee.app/api/v1/mailboxes \
-H "Authorization: Bearer $MAYLEE_KEY"A key is mk_ followed by 40 letters and digits. Anything else is rejected before reaching the database. Session cookies are never accepted on this surface, whatever their validity.
Create a key
- In the Maylee app, open Settings, then API keys.
- In the Maylee API Key section, name the key after what it is for ("CRM integration"), not after yourself: that name is what you read the day you need to revoke it.
- Tick the scopes the integration needs, and Send emails only if it really sends email.
- Create the key and copy the secret. It is shown once: only a SHA-256 hash of it is stored, so it can never be displayed again.
Only workspace owners and admins can create and revoke keys. The number of active keys depends on the plan: 2 on Free, 10 on Premium, 50 on Expert. Beyond it, creating a key returns 409 and asks you to revoke one.
Keep keys server-side
A key gives access to every mailbox of the workspace. Never ship it in a browser, a mobile app or a public repository. Revoking it in Settings, API keys cuts off every integration that uses it, within a minute at most.
Scopes
Two scopes, and one separate permission.
| Scope | Grants |
|---|---|
read | List and read emails, bodies and threads, drafts, mailboxes, labels, AI label rules, views, inbox filters, auto-forward rules and their logs. |
write | Mark as read or starred, move to trash, apply and remove labels, bulk operations, create drafts, manage labels, AI label rules, views and inbox filters, classify existing emails. |
A request that lacks a scope gets 403 INSUFFICIENT_SCOPE, with the missing scope in details.required and the key's scopes in details.granted. Each endpoint of the API reference states the scope it needs.
The Send emails permission
Making email leave the workspace needs the write scope and the Send emails option of the key (allowOutboundSend in the API). The option can only be ticked together with write. It gates:
- sending an email with
POST /drafts/send; - creating, changing or deleting an auto-forward rule;
- turning on auto-reply on an AI label rule (
autoReplyEnabled: true).
Without it, these requests get 403 OUTBOUND_SEND_NOT_ALLOWED. Creating a draft for a person to review does not need it: nothing leaves the workspace.
When a key stops working
| Response | Meaning |
|---|---|
401 INVALID_API_KEY | The Authorization header is missing, malformed, or the key is unknown. |
401 API_KEY_REVOKED | The key was revoked. Create a new one. |
401 API_KEY_EXPIRED | The key had an expiry date and it has passed. details.expiredAt says when. |
403 WORKSPACE_SUSPENDED | The workspace is suspended. Reactivate the subscription. |
401 responses carry no X-RateLimit-* headers: the key is resolved before the counters are read.
MCP server
AI assistants connect to the MCP server with OAuth, or with the same API keys: see Connect.
Introduction
Build on Maylee, the AI email client. Read, search, triage and send email across every mailbox of a workspace, from your own code or from an AI agent.
Common tasks
Read a conversation, search, mark as read, send, prepare a draft for review, reply in a thread and let Maylee classify email, with copyable requests.