Limits and troubleshooting
The quotas and size limits of the Emelia MCP server, the errors you can meet and what they mean, and prompts to try first.
Limits
The server has no quota of its own: it uses the ones of your account.
- Emelia tools. The tools of the
campaigns,linkedin_scraper,mailboxesandaccountcategories count in your per minute quota (30 to 1,000 requests per minute depending on your plan). Thelistsandenrichmenttools are not counted. Over the quota, a tool fails with "Emelia API rate limit reached. Wait a moment and retry."; the quota frees up within a minute. - Inbox tools. They count in the quotas of the inbox: 60 requests per minute and 10,000 per month per Emelia account, and a tool that acts on several emails costs one request per email. On top of that, a few safety limits apply per hour: 50 sends (send, schedule or unsubscribe), 200 recipients, 500 emails moved to Trash or Spam, and 30 Magic Reply suggestions.
The quotas of the inbox tools are shared with the Emelia Inbox API.
Requests to the server are limited to 4 MB. The files you send with upload_campaign_attachments, upload_linkedin_voice_note or add_draft_attachment travel in base64 inside that request: about 3 MB of file per call.
Each tool returns the whole API response, except the CSV files of export_campaign, export_list, get_list_export and download_linkedin_scraper, cut at 100,000 characters on a line boundary, with a note that gives the number of lines shown. Ask for small pages on big lists, and narrow the exports with their filters. The inbox tools shorten long conversations and attachments themselves, and say so in their answer.
Troubleshooting
| Symptom | Cause |
|---|---|
Authentication required. ... (JSON-RPC error -32001, HTTP 401) | No sign-in and no API key reached the server. Sign in from your client (in Claude Code: /mcp, emelia, Authenticate), or check the header that carries the key. |
| "The Emelia access token is invalid, expired or revoked. Reconnect Emelia." (HTTP 401) | The access expired, or the assistant was disconnected in Settings, API & Webhooks, Connected apps. Most clients sign in again on their own; otherwise reconnect the server. |
| "This connection request has expired or was already used." on the Emelia page | The sign-in page waits 10 minutes, and each link works once. Start the connection again from your client. |
| "Emelia is temporarily unavailable, retry in a moment." (HTTP 503) | Emelia could not check the sign-in. Retry a little later. |
Unknown toolset: ... (JSON-RPC error -32602, HTTP 400) | A category of ?toolsets= is misspelled. The message lists the valid ones; see Tool categories. |
| "Emelia refused the credentials of this connection" | The API key is wrong, disabled or deleted, the access of the assistant was revoked, or the campaign of get_campaign_stats does not exist. Sign in again, or create a new key in Settings, API & Webhooks. |
| "Emelia API rate limit reached. Wait a moment and retry." | The per minute quota of your account is reached (HTTP 429 RATE_LIMITED). Wait a minute. |
| "Emelia API error (400): ..." with a JSON body | The API refused the request; the message says why, for example "country" is required. |
| "Open the Inbox in Emelia once to set it up, then reconnect." | The client still shows the inbox tools of an earlier connection, and the account has no Inbox. Open the Inbox tab of the Emelia app once, then reconnect. |
| "The Emelia inbox is temporarily unavailable, retry in a moment." | The inbox did not answer. Retry a little later; the Emelia tools keep working. |
405 on /mcp | The server only answers POST. A GET gets 405 with a key, and 401 with the sign-in header without one. |
406 or 415 | The client does not send Accept: application/json, text/event-stream or Content-Type: application/json. |
| A tool is missing | Its category is not in ?toolsets=. For an inbox tool, the Inbox was never opened in Emelia (open it once, wait a few minutes, then reconnect), or the inbox did not answer when the client listed the tools (reconnect). The legacy campaigns have no tools: use the REST API. |
Prompts to try
- "List my campaigns and tell me which ones are running."
- "Add Claire Fontaine, CTO at Nexora, claire.fontaine@nexora.io, to my Q4 SaaS founders list." She enters the campaigns of that list.
- "What is the reply rate of my Q4 SaaS founders campaign since Monday, step by step?"
- "Find and verify the email of Hugo Martin at Brightlane, in France, then add him to my Warm leads list."
- "Which of my mailboxes are disconnected, and which have a low warmup score?"
- "Read the replies I received this week, tell me who asks for a meeting, and draft an answer to each of them. Do not send anything."
- "Read the sequence guide, then write a sequence for my Q4 SaaS founders campaign: an email, a LinkedIn invitation two days later, and a follow-up email three days after that if they did not reply. Show it to me before you save it."