---
name: emelia-api
description: Use the Emelia REST API and the Emelia MCP server correctly. Emelia is a B2B prospecting platform (multichannel cold email, LinkedIn and WhatsApp campaigns, contact lists, Email Finder, Phone Finder, Email Verifier, replies, inbox, webhooks, LinkedIn extraction). Use this skill whenever you write code, scripts or HTTP calls against api.emelia.io, build an integration with Emelia (CRM sync, Make or n8n replacement, enrichment pipeline, webhook receiver), create or edit an Emelia campaign by API or with the Emelia MCP tools (mcp__emelia__*), push contacts into Emelia lists, connect the Emelia MCP server (mcp.emelia.io) to an AI client, or debug an Emelia API or MCP error.
---

# Emelia API

Full documentation: https://docs.emelia.io (index for agents: https://docs.emelia.io/llms.txt; every page has a Markdown version at `<url>.md`). OpenAPI spec: https://docs.emelia.io/openapi/emelia.json. When a detail is not in this file, read the matching `.md` page rather than guessing.

## Setup

- Base URL: `https://api.emelia.io`. Lists and contacts live under `https://api.emelia.io/lists` (so `POST /lists/list`), served by a separate service: same key, but errors use `message`, and real 404, 413 and 422 statuses.
- Auth: header `Authorization: <API key>`, the raw key. `Bearer <key>` is accepted. The key is exactly 48 letters and digits: always trim it. Read it from `EMELIA_API_KEY`, never hard-code it, never print it, never put it in a URL.
- JSON bodies with `Content-Type: application/json`, except multipart uploads (attachments, voice notes).
- One key opens the whole account (no scopes). There is no sandbox: every call acts on real data.
- Ids are MongoDB ObjectIds (24 lowercase hex). Dates are ISO 8601 UTC.
- The Emelia MCP tools (`mcp__emelia__*`) call these same routes. When they are connected, read "The Emelia MCP server" below to choose between the tools and code.

## The model, in three rules

1. **Contacts live in lists; campaigns read lists.** Adding a contact to a list used by a campaign makes it enter the campaign. To feed a campaign, add to its list. Deleting a contact from a list removes it from those campaigns.
2. **Every campaign is multichannel.** Create every campaign with `POST /advanced/campaigns`, whatever the channel. Its step tree decides email, LinkedIn, WhatsApp or several. Never create campaigns with `/emails/campaigns` or `/linkedin/campaigns` (legacy system).
3. **Enrichment is asynchronous.** `POST /tools/...` returns a `jobId` at once; poll `GET /tools/.../{jobId}` every 3 to 5 seconds until `data.status` is not `running`.

## Endpoints you will use most

| Purpose | Call |
|---|---|
| Check the key | `GET /advanced/campaigns` |
| Create a list | `POST /lists/list` `{"name"}` -> 201 `{listId}` |
| Declare a custom variable (before importing) | `POST /lists/custom-variable` `{"technicalName", "schema": "lead"|"company", "displayName"?}` (422 = already exists, fine) |
| Add one contact | `POST /lists/list/{listId}/contacts?updateIfExists=true` with a flat object |
| Add up to 100 contacts | `POST /lists/list/{listId}/contacts/batch?updateIfExists=true` `{"contacts":[...]}` |
| Find a contact in a list | `GET /lists/list/{listId}/rows?email=...` (or `linkedinUrl=`); items carry `id` = leadId |
| Which lists hold a person | `GET /lists/list?leadSearch=<email or LinkedIn URL>&page=1&limit=25` |
| Update a contact | `PATCH /lists/contacts/{leadId}` with only the changed fields |
| Delete a contact / a list | `DELETE /lists/list/{listId}/rows/{leadId}` / `DELETE /lists/list/{listId}` (permanent) |
| Export a list | `POST /lists/list/export` `{"listIds": [...], "async": true}` (202 + jobId above 5,000 contacts) |
| Create a campaign | `POST /advanced/campaigns` `{"name", "timeZone"?}` -> `{campaignId}` (name unique per account) |
| Read a campaign | `GET /advanced/campaigns/{id}` (step tree in `campaign.steps`) |
| Set the sequence | `PATCH /advanced/campaigns/{id}/steps` `{"steps": {tree}}` |
| Schedule and volumes | `PATCH /advanced/campaigns/{id}/settings` `{"settings": {...}}` |
| Senders | `PATCH /advanced/campaigns/{id}/identities` `{"identities": [{"name", "email"?, "linkedin"?, "whatsapp"?}]}` |
| Attach lists | `PATCH /advanced/campaigns/{id}/recipients` `{"lists": [...], "excludedLists": [...]}` |
| Test email | `POST /advanced/campaigns/{id}/test-email` `{"stepId", "versionId", "email"}` |
| Start / pause | `POST /advanced/campaigns/{id}/start` / `.../pause` (no body) |
| Stats | `GET /stats/advanced?campaignId=...` |
| Replies | `GET /advanced/campaigns/{id}/activities?types=MAIL_REPLIED,LINKEDIN_REPLIED&page=0` (30 per page, page from 0) |
| Export CSV | `GET /advanced/campaigns/{id}/export?type=replies` (or `contacts`, `activities`) |
| Find email | `POST /tools/find/email` `{"fullname", "companyName", "country", "companyWebsite"?}` |
| Find phone | `POST /tools/find/phone` `{"linkedinUrl"}` (public `linkedin.com/in/` URL) |
| Verify email | `POST /tools/verify/email` `{"email"}` |
| Answer a reply | `POST /emails/reply` `{"content", "providerId" or "senderEmail", "messageId"?, "to"?, "subject"?}` |
| Blacklist | `POST` / `DELETE /emails/blacklists/contact` `{"email": "<address or domain>"}`; LinkedIn: `/emails/blacklists/linkedin` `{"value"}` |
| Mailboxes | `GET /email-providers` (`_id`, `senderEmail`, `disconnected`) |
| Tracking domains | `GET /domains`; add: `POST /domains/create` `{"domain"}` (subdomain, CNAME to `emelia.link`); attach: `POST /domains/assign` `{"providerIds", "domainId"}` (`null` detaches); delete: `DELETE /domains/{providerId}` (mailbox id; deletes it for every mailbox, `?onlyUnlink=true` detaches this one only) |
| Webhooks | `POST /webhook`, `GET /webhook`, `POST /webhook/{hookId}/test`, `DELETE /webhook` |
| Credit history | `GET /credits/usage?page=1&limit=50` |

LinkedIn and WhatsApp accounts are connected in the Emelia app; there is no documented route to list them. Reuse the ids found in the `identities` of an existing campaign, or ask the user to set the identities in the app.

## Contacts: how keys are read

The body of a contact is a flat object of strings, numbers or booleans (an array or object fails the row; `null` and empty strings are ignored, so a field cannot be cleared). Each key is resolved in order:

1. standard field by name or alias, any case (`First Name`, `Prénom` -> `firstName`);
2. standard field by technical name, also as a prefix or suffix of 3+ characters (`job` -> `jobStartDate`, `last` -> `lastContacted`: avoid short keys);
3. existing custom variable of the account;
4. a key ending in `id` becomes a custom variable;
5. **by the value**: email -> `email`, 6+ digits -> `phone`, `linkedin.com/in/` -> `linkedinUrlProfile`, other URL -> company `websiteUrl`;
6. otherwise a new custom variable (returned in `createdCustomVariables`).

Consequences:
- Use the exact standard keys: `firstName`, `lastName`, `email`, `phone`, `mobilePhone`, `jobTitle`, `linkedinUrlProfile` (person), `linkedinCompanyUrl` (company page), `companyName`, `companyDomain`, `websiteUrl`, `city`, `country`. `mobile` maps to `phone`.
- A number under an unknown key (registration number, order number, a date) lands in `phone`: declare the custom variable first with `POST /lists/custom-variable`.
- Duplicates are matched in the list and its linked lists on the exact `email` (case sensitive: send lowercase), then on the exact `linkedinUrlProfile` string. A duplicate is not created again: `duplicate: true` with the existing `leadId`. `?updateIfExists=true` (query parameter, the exact string `true`) updates it instead (`updated: true`). **A contact without email and without LinkedIn URL is never deduplicated**: retries create copies.
- Batch: 1 to 100 contacts, 5 MB per body (413 `PAYLOAD_TOO_LARGE`). Read `results[]` (same order as input, `index`, `error` on failed rows) and report failures. `created + duplicates + failed = total`.
- Reading back (paginated mode): each contact only carries the columns visible in the app; use the exact lookup (`?email=`) for the full object.

## Campaign sequence (step tree)

- `steps` is an object (the root), not an array: `{"_id": "START", "stepType": "START", "delay": {"amount": 0, "unit": "DAYS"}, "next": {...}}`.
- **Ids: omit every `_id` except `"START"` on the root; the server generates them.** If you must write one, it is a MongoDB ObjectId: 24 lowercase hex chars (`crypto.randomBytes(12).toString('hex')`, `secrets.token_hex(12)`). Never a UUID, never a label. Any other id is refused at save time (HTTP 400, `INVALID_STEP_ID`, `INVALID_VERSION_ID` or `DUPLICATE_STEP_ID`).
- **Give every action step at least one version**, including `VISIT` and `LIKE`: `"versions": [{}]`.
- `stepType`: `EMAIL`, `CONNECTION`, `MESSAGE`, `INMAIL`, `VISIT`, `LIKE`, `WHATSAPP`, `TASK`, `CONDITION`, `END_OF_CAMPAIGN`. No `LINKEDIN_` prefix, no `WAIT` (a wait is the `delay` of the next step). `FOLLOW`, `AUDIO` and `API_CALL` are accepted when saved but nothing runs them, and the step is never marked as done: do not use them.
- LinkedIn voice note: a `MESSAGE` step whose `versions[0].attachments` is `[{"name", "url", "mediaType": "AUDIO", "duration"}]`, with the `name`, `url` and `duration` returned by `POST /advanced/linkedin/audio` (multipart field `audio`). `duration` is in milliseconds.
- `delay`: `{"amount": n, "unit": "DAYS"|"HOURS"|"MINUTES"}` from the previous action. The delay of the first action is ignored. On a `CONDITION`, the delay is the observation window.
- EMAIL versions: `{"subject", "message", "disabled": false}`; several versions = A/B test. `message` is HTML: `<p>` per paragraph, `<p></p>` for a blank line. Empty `subject` on a follow up keeps the thread; the first email needs a subject.
- MESSAGE and WHATSAPP versions are successive messages, not A/B. A `MESSAGE` right after a `CONNECTION` waits for the acceptance (up to a year).
- Variables: `{{firstName}}`, `{{lastName}}`, `{{companyName}}`, `{{jobTitle}}`, any contact field or custom variable, `{{companyCountry}}`, `{{companyCity}}`, `{{signature}}`, `{{unsubscribe_link}}` (in an `<a href>`). Spintax: `{Hi|Hello}`.
- `CONDITION`: `{"conditions": {"field", "operator", "value"}, "yes": {...}, "no": {...}}`. `field` is an event in capitals (`ACCEPTED`, `MAIL_REPLIED`, `LINKEDIN_REPLIED`, `OPENED`, `CLICKED`, `BOUNCED`, `UNSUBSCRIBED`, `TASK_COMPLETED`, with `EQUAL` and `"true"`) or a contact field with `$` (`$email`, `$jobTitle`). Operators evaluated: `EQUAL`, `DOES_NOT_EQUAL`, `GREATER`, `LOWER`, `CONTAINS`, `DOES_NOT_CONTAIN`, `IS_EMPTY`, `IS_NOT_EMPTY`; anything else (`NOT_EQUAL`, `GREATER_THAN`) is saved and always false. `OPENED`/`CLICKED` need tracking on. Branches never merge.
- The tree is replaced whole: read `GET /advanced/campaigns/{id}`, modify, send the whole tree back. On a campaign that already sent, keep every existing `_id`.

## Campaign rules that cause most failures

- A `RUNNING` campaign refuses changes to name, settings, identities and steps: pause, patch, start. Attached lists can change while running.
- Settings: always send `start`, `end` (`HH:mm`), `trackOpens`, `trackLinks`, `blacklistUnsub`; the rest is merged. `dailyEmailAdded` and `dailyEmailLimit` 1 to 500, limit >= added. `dailyLinkedinAdded` max 40 with a `CONNECTION` step, 80 otherwise. `dailyWhatsappAdded` 1 to 30. `days` 0 (Monday) to 6.
- Defaults of a new campaign: Europe/Brussels (unless `timeZone`), Monday to Friday, 08:00 to 17:00, 35 new contacts and 100 emails per day, tracking off, a reply stops the sequence.
- `lists` and `identities` replace the previous values entirely. Identities take account ids (`_id` from `/email-providers`), not addresses. Attach only the mailboxes of the campaign's sender.
- Start errors are `400` with a stable `code`, first failing check only: `SUBSCRIPTION_REQUIRED`, `NO_IDENTITY_SET`, `EMAIL_VERSION_NO_SUBJECT`, `EMAIL_PROVIDER_DISCONNECTED`, `LINKEDIN_ACCOUNT_AMBIGUOUS`, `MC_LINKEDIN_DAILY_LIMIT_CONNECTION`, `NO_RECIPIENTS`, `TOO_MANY_RECIPIENTS` (30,000 max), `RECIPIENTS_NO_EMAIL`...
- Connecting a mailbox or a LinkedIn account, and the subscription a start needs, happen in the Emelia app.

## Enrichment

- Find email: `country` (ISO 2 letters, e.g. `FR`) is required: without it, `400 "country" is required`. 1 credit, refunded when no email is found (not on timeout). A search can take up to about 4 minutes.
- Result: `GET /tools/find/email/{jobId}` -> `{"data": {"status": "running"|"done"|"error", "email"?, "qualification"}}`. `done` without `email` = not found. An email found as `valid` is already verified: do not verify it again.
- Find phone: 50 credits, refunded when no number is found; no fixed upper bound on the wait. Verify: 0.25 credit, never refunded; the job ends in `error` after about 60 seconds without a verdict.
- **Never re-POST a job that may have started**: it starts and bills a second job. Poll the existing `jobId`. History: `GET /tools/find/email` (page from 1).
- For many contacts: filter first, start all jobs, then poll them. Stop at the first "You do not have enough credits to perform this action" (400).
- Confirm the credit cost with the user before any bulk enrichment.

## Webhooks

- Create: `POST /webhook` with `{"hookUrl", "campaignId", "type": "advanced", "events": [...]}`. `campaignId` is a campaign id or `ALL_CAMPAIGNS`. Always send `type: advanced`: without it the route works on legacy campaigns, and `ALL_CAMPAIGNS` answers `success: true` without touching advanced campaigns.
- Event names are not validated, a misspelled one never fires. A URL registered twice on a campaign receives everything twice: to change events, delete then create.
- `POST /webhook/{hookId}/test` sends a fake `MAIL_REPLIED` event. `GET /webhook` lists the registrations with their `id`. `DELETE /webhook` takes `{"hookUrl", "campaignId", "type": "advanced"}` in the body.
- Event names of current campaigns: `EMAIL_SENT` (not `MAIL_SENT`), `OPENED`, `CLICKED`, `WEBSITE_VISITED` (pixel: the contact triggered a pixel rule set to create a campaign activity, the rule name is in `customData.rule`; `VISITED` is a LinkedIn profile visit), `MAIL_REPLIED`, `BOUNCED`, `UNSUBSCRIBED`, `VISITED`, `INVITED`, `ACCEPTED`, `MESSAGE_SENT`, `INMAIL_SENT`, `LIKED`, `LINKEDIN_REPLIED`, `RE_REPLY_EMAIL`, `RE_REPLY_LINKEDIN`, `WHATSAPP_MESSAGE_SENT`, `WHATSAPP_REPLIED`, `CAMPAIGN_ENDING`. `RE_REPLY_*` = each later message of a contact who already replied, webhook only: not in the activity feed, not replayed, nothing once the campaign is finished.
- Payload: JSON `POST` with `event`, `campaign` (name), `contact` (custom variables then standard fields), `date`, `step`, and for replies `reply`, `sentiment` `{classification, score}`, `sender`, `messageId`.
- Deliveries are not signed, not retried on HTTP errors, not ordered and carry no event id: use a hard to guess URL, answer 2xx at once, process async, and reconcile with the activity feed if you cannot miss events.

## LinkedIn accounts

- Connect an account without touching its credentials: `POST /linkedin/invitations` with `{"email", "sendEmail": false}` returns `url` (valid 7 days) and `token`. Follow it with `GET /linkedin/invitations/{token}`; `accountId` is set once connected. Add `authId` to reconnect an existing account.
- `GET /linkedin/accounts` lists the accounts: `status` is `active`, `connecting`, `disconnected` or `disabled`. Never use `GET /linkedin/authes` for this.
- `POST /account-webhooks` with `{"url", "events": ["LINKEDIN_ACCOUNT_DISCONNECTED"]}` notifies a disconnection, checked every 5 minutes. HTTPS only, 10 URLs per account.

## Errors and limits

- Error body: `{"error": "...", "code"?, "params"?}` on the main API (branch on `code` when present); `{"message": "...", "code"?}` on `/lists`. "Not found" is a `400` on the main API, a `404` on `/lists`. Unknown paths answer an HTML 404.
- `401 {"error": "Authentication required"}` = bad, disabled or untrimmed key. On `/stats/...`, a `401` can also mean "campaign not found".
- Rate limit per account (all keys together), per fixed minute: 30 without a plan, 100 Start, 300 Grow, 1,000 Scale. `/tools` and `/lists` are not counted. Over the limit: `429 {"error": "Rate limit exceeded. Maximum <n> requests per minute.", "code": "RATE_LIMITED"}` with `Retry-After` in seconds: wait that long, then go slower.
- Pagination: lists `page` from 1 (`limit` max 100), list rows `page` from 1 (`pageSize` max 100), activities and campaign contacts `page` from 0, tool and credit histories `page` from 1. Campaigns, mailboxes and warmups are not paginated.

## Emelia Inbox API

The emails of the unified inbox have their own API: `https://api.emelia.io/inbox/api/v1`, with the same Emelia API key in `Authorization` (it can send emails). Errors are `{"code", "error", "details"?}`; 60 requests per minute and 10,000 per month per account, separate from the Emelia API rate limit. The inbox tools of the MCP server share these quotas. Docs: https://docs.emelia.io/docs/inbox-api.md, spec: https://docs.emelia.io/openapi/inbox.json.

## The Emelia MCP server

`https://mcp.emelia.io/mcp` (Streamable HTTP, `POST` only) exposes the whole API except the legacy campaigns as tools: 82 Emelia tools, plus 61 inbox tools once the Inbox has been opened in the Emelia app (143 in all). Docs: https://docs.emelia.io/docs/mcp.md, then `/docs/mcp/categories.md`, `/docs/mcp/tools.md`, `/docs/mcp/troubleshooting.md`.

- **Tools or code.** Use the tools to act in the account during the conversation: read campaigns and stats, add a few contacts, fix a sequence, answer replies. Write code against the REST API for anything repeatable, scheduled, run outside the conversation, or too large for tool results (thousands of contacts). The tools call the same routes, so every rule of this file applies to them too.
- **Sequence.** Call `get_campaign_sequence_guide` before writing or changing a sequence. `update_campaign_steps` replaces the whole tree, as `PATCH .../steps` does.
- **Connect.** Name the server `emelia`, so that its tools are `mcp__emelia__<tool>`. The default is to sign in with the Emelia account (OAuth): in Claude Code, `claude mcp add --transport http --scope user emelia https://mcp.emelia.io/mcp`, then `/mcp`, `emelia`, **Authenticate**, and **Authorize** on the Emelia page that opens. In claude.ai or Claude Desktop, add a custom connector with the URL, then click **Connect**. For CI, scripts or a machine without a browser, pass an API key instead, in `Authorization` (raw or `Bearer <key>`) or `X-Api-Key`. In a shared `.mcp.json`, write `"Authorization": "${EMELIA_API_KEY}"`, never the key.
- **OAuth.** The sign-in gives the tools access, not an API key: code still needs `EMELIA_API_KEY`. The access lasts 30 days and most clients renew it. **Settings, API & Webhooks, Connected apps** lists the connected assistants; **Disconnect** cuts one off within 30 seconds.
- **Categories.** `?toolsets=campaigns,lists,enrichment` turns on only those categories: `campaigns`, `lists`, `enrichment`, `linkedin_scraper`, `mailboxes`, `account`, `inbox`, `inbox_settings`. Claude loads tools on demand, so keep them all there. Give Cursor, VS Code and ChatGPT only what the task needs. An unknown category gets HTTP `400` with the valid list. A tool of a category that is off cannot be called, even when another tool's description names it.
- **Limits.**
  - Requests are capped at 4 MB. Files sent to the upload tools travel in base64: about 3 MB of file per call.
  - The CSV of `export_campaign`, `export_list`, `get_list_export` and `download_linkedin_scraper` is cut at 100,000 characters.
  - `find_email`, `find_phone`, `verify_email` and `export_list` wait up to 90 seconds, then return the `jobId`. Read it later with `get_enrichment_result` or `get_list_export`, and never start the same job again.
  - `find_email` needs `country` even though the tool marks it optional.
  - The `campaigns`, `linkedin_scraper`, `mailboxes` and `account` tools count in the per minute quota of the account.
- **Inbox tools.**
  - Without `confirm: true`, they refuse to send, schedule, unsubscribe, create or change an auto-forward rule, and most deletions. Set it only after the user approved that exact email or action.
  - At most 60 emails per call.
  - Per hour: 50 sends, 200 recipients, 500 emails moved to Trash or Spam.
  - Their links open https://v3.emelia.io/inbox.
- **Errors.**
  - `Authentication required` (`-32001`, HTTP 401): no sign-in and no key.
  - "The Emelia access token is invalid, expired or revoked": reconnect.
  - "Emelia refused the credentials of this connection": a wrong or disabled key, or revoked access. With `get_campaign_stats`, it also means an unknown campaign.
  - A wrong key still lists the tools: the key is checked at the first call.
  - `406` or `415`: the request needs `Content-Type: application/json` and `Accept: application/json, text/event-stream`.
  - `set_warmup` with `enabled: false` fails with "Warmup not found": turn the warmup off in the app.
  - Health check: `https://mcp.emelia.io/mcp/health` answers `{"ok":true}`.

## Safety

- Ask before anything that sends a message, starts a campaign, deletes data or spends credits. Show what will happen (recipient count, cost) and wait for an explicit yes. With the MCP tools too: `start_campaign` and `send_campaign_test_email` send real messages, although clients do not flag them as destructive.
- Never print, log or commit the API key, an MCP access token, or LinkedIn session cookies.
- Read the campaign back after each write to confirm what Emelia now holds.
