MailFleet API reference
A two-way REST API over your workspace — read campaigns, leads, replies and stats, and create campaigns, add leads and reply to leads from your own tools. JSON in, JSON out, one bearer token, 120 requests a minute.
Authentication
Create a key in Settings → API & webhooks and choose its access: Read & write (read everything, and make changes — create campaigns, add leads, reply to leads) or Read only (for dashboards). Keys created before the API could write are read-only; a change sent with one is answered 403 read_only_key. Keys start with sk_live_ and are shown once — only a hash is stored, so a lost key is revoked and replaced, never recovered. Treat a key as a password: a read & write key can email your leads.
curl -s "https://mailfleet.co/api/v1/stats" \
-H "Authorization: Bearer sk_live_your_key"
An X-API-Key: sk_live_… header works identically if a bearer token is awkward in your client.
API access is a Pro and Scale feature. A key can be created on any plan, but requests from a Trial or Basic workspace are answered with 403. GET /api/v1 needs no key at all and lists what is available.
Conventions
- Base URL —
https://mailfleet.co/api/v1. Every path below is relative to it. - Field names are
snake_case(first_name,sent_today,daily_limit). - Lists accept
limit(1–100, default 25) andoffset(default 0), and answer with{ object: "list", data: [...], pagination: { total, limit, offset, has_more } }. - Scope — a key only ever sees its own workspace. There is no cross-workspace read, for anyone.
- Reads and writes —
GETreads;POST,PUT,PATCHandDELETEchange things and need a read & write key. Every change runs the same code as the app, so it behaves exactly as clicking it would. To be told when something happens rather than polling for it, use webhooks — on every plan, and manageable through the API. - Safe retries — send an
Idempotency-Keyheader (a UUID) with a request that creates or sends something. A retry with the same key and body gets the first response back (withIdempotent-Replayed: true) instead of doing it twice. Keys last 24 hours. - Bodies are JSON (
Content-Type: application/json), up to 5 MB — 2,000 leads with custom fields fit easily. - Rate limit — 120 requests a minute per key. Every response says where you are:
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(Unix seconds when the minute starts over). A429also carriesRetry-After, in seconds — slow down before you reach it. - Reporting — numbers per day in your timezone, per step and A/B variant, every event as a feed, and a whole campaign as one CSV or JSON file: the
/campaigns/{id}/stats,/steps/stats,/eventsand/exportendpoints below, counted exactly as the app counts. - Machine-readable — the OpenAPI 3.0 document describes everything on this page; point your generator at it.
GET /campaigns
List campaigns
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
status | DRAFT · SENDING · PAUSED · FINISHED | query | Filter by status. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns?status=SENDING" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "SENDING",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-08T08:02:11.000Z",
"created_at": "2026-09-05T16:41:57.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /campaigns
Create a campaign
Create a draft email campaign — with its steps, sender_ids and schedule in the same call if you have them, or set each later. It starts with no steps (never a placeholder email) and sends nothing until you start it with POST /campaigns/{id}/start, which runs the same checks as Launch in the app.
Needs a read & write key. Send an Idempotency-Key so a retried request can't create it twice.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
name | string | required | The campaign's name. |
steps | array of object | optional | The sequence, in order (see PUT /campaigns/{id}/steps). |
sender_ids | array of string | optional | Mailboxes to send from — ids from GET /senders. Empty or left out = every healthy sender. |
schedule | object | optional |
Request
curl -s -X POST "https://mailfleet.co/api/v1/campaigns" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"name":"Acme — Q4 outbound","steps":[{"type":"email","subject":"Quick question about {{company}}","body":"Hi {{first_name|there}},\n\nNoticed {{company}} is hiring SDRs — worth a short call?"},{"type":"email","wait_days":3,"subject":"Re: Quick question about {{company}}","body":"Bumping this in case it got buried."}],"sender_ids":["snd_2e10b4"],"schedule":{"timezone":"America/New_York","days":["Mon","Tue","Wed","Thu","Fri"],"window_from":"09:00","window_to":"16:30"}}'
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "DRAFT",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"type": "email",
"step_count": 128,
"sender_ids": [
"…"
],
"schedule": {
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
},
"settings": {
"tracking": {
"open": true,
"click": true,
"plain_text": false,
"tracking_domains": [
{
"sending_domain": "outbound.acme.com",
"host": "track.outbound.acme.com"
}
]
},
"utm": {
"source": "outbound",
"medium": "email",
"campaign": "q4-outbound",
"content": "step-{{step_number}}",
"term": null
},
"unsubscribe_line": {
"text": "Not the right person? Reply “no thanks” and I’ll stop.",
"reads": "Not the right person? Reply “no thanks” and I’ll stop. · Unsubscribe"
}
}
}
GET /campaigns/{id}
Get a campaign
The campaign's stats, plus its type, schedule, senders (sender_ids; empty = every healthy sender), how many steps it has, and its tracking, UTM and unsubscribe-line settings (settings) — check settings.tracking.click before trusting a click count.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "DRAFT",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"type": "email",
"step_count": 128,
"sender_ids": [
"…"
],
"schedule": {
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
},
"settings": {
"tracking": {
"open": true,
"click": true,
"plain_text": false,
"tracking_domains": [
{
"sending_domain": "outbound.acme.com",
"host": "track.outbound.acme.com"
}
]
},
"utm": {
"source": "outbound",
"medium": "email",
"campaign": "q4-outbound",
"content": "step-{{step_number}}",
"term": null
},
"unsubscribe_line": {
"text": "Not the right person? Reply “no thanks” and I’ll stop.",
"reads": "Not the right person? Reply “no thanks” and I’ll stop. · Unsubscribe"
}
}
}
PATCH /campaigns/{id}
Rename a campaign or change its tracking, UTM tags and unsubscribe line
Send any of name and settings; what you leave out keeps its value. Tracking: open, click and plain_text — a plain-text email can't carry a tracking pixel or tracked links, so plain_text: true turns both off, and asking for tracking with plain text on is refused. Each sending domain's tracking domain is set up in the app (Settings → Tracking) and only read here. UTM tags: an object turns them on, its fields merged over the ones set (null or "" clears one); utm: null turns them off and clears them. Once on, every link in the campaign's emails goes out with the tags added — never one a link already has — and {{step_number}} / {{variant}} in a value become the email's step (1, 2 …) and A/B variant (A, B …). Unsubscribe line: a short sentence and an Unsubscribe link in small type after the signature, off unless turned on — an object turns it on (text sets the sentence, up to 300 characters; "" leaves the link alone; left out keeps the one set), null turns it off. Every email carries the one-click List-Unsubscribe header whether the line is on or off. Changes apply to emails sent from then on.
Steps, senders, schedule, start and pause have their own endpoints. A Multi Channel campaign with an "Opened" or "Clicked" check can't switch tracking off (409). All or nothing: a refused setting changes nothing.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Body
| Field | Type | Notes | |
|---|---|---|---|
name | string | optional | |
settings | object | optional |
Request
curl -s -X PATCH "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"settings":{"tracking":{"open":true,"click":true,"plain_text":false},"utm":{"source":"outbound","medium":"email","campaign":"q4-outbound","content":"step-{{step_number}}"}}}'
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "DRAFT",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"type": "email",
"step_count": 128,
"sender_ids": [
"…"
],
"schedule": {
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
},
"settings": {
"tracking": {
"open": true,
"click": true,
"plain_text": false,
"tracking_domains": [
{
"sending_domain": "outbound.acme.com",
"host": "track.outbound.acme.com"
}
]
},
"utm": {
"source": "outbound",
"medium": "email",
"campaign": "q4-outbound",
"content": "step-{{step_number}}",
"term": null
},
"unsubscribe_line": {
"text": "Not the right person? Reply “no thanks” and I’ll stop.",
"reads": "Not the right person? Reply “no thanks” and I’ll stop. · Unsubscribe"
}
}
}
DELETE /campaigns/{id}
Delete a campaign
As Delete does in the app: its sequence, enrolments, record of sent emails and tasks go with it. The leads, their lists and the replies they sent stay (no longer linked to it).
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s -X DELETE "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"deleted": true
}
POST /campaigns/{id}/start
Start or resume a campaign
Start a draft or resume a paused campaign — the same checks as Launch in the app: steps with text, leads to send to, and an active sender. A refusal (400 not_ready) lists what's missing in error.blockers. Emails go out within the campaign's schedule. Starting one that's already sending changes nothing.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/start" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "DRAFT",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"type": "email",
"step_count": 128,
"sender_ids": [
"…"
],
"schedule": {
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
},
"settings": {
"tracking": {
"open": true,
"click": true,
"plain_text": false,
"tracking_domains": [
{
"sending_domain": "outbound.acme.com",
"host": "track.outbound.acme.com"
}
]
},
"utm": {
"source": "outbound",
"medium": "email",
"campaign": "q4-outbound",
"content": "step-{{step_number}}",
"term": null
},
"unsubscribe_line": {
"text": "Not the right person? Reply “no thanks” and I’ll stop.",
"reads": "Not the right person? Reply “no thanks” and I’ll stop. · Unsubscribe"
}
}
}
POST /campaigns/{id}/pause
Pause a campaign
Nothing more goes out until it's started again. Pausing a paused campaign changes nothing; a draft or finished one answers 409 not_sending.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/pause" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "DRAFT",
"stats": {
"leads": 2400,
"sent": 1890,
"opened": 812,
"clicked": 96,
"replied": 74,
"interested": 21,
"bounced": 18,
"skipped": 12,
"delivered": 128,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
},
"started_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"type": "email",
"step_count": 128,
"sender_ids": [
"…"
],
"schedule": {
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
},
"settings": {
"tracking": {
"open": true,
"click": true,
"plain_text": false,
"tracking_domains": [
{
"sending_domain": "outbound.acme.com",
"host": "track.outbound.acme.com"
}
]
},
"utm": {
"source": "outbound",
"medium": "email",
"campaign": "q4-outbound",
"content": "step-{{step_number}}",
"term": null
},
"unsubscribe_line": {
"text": "Not the right person? Reply “no thanks” and I’ll stop.",
"reads": "Not the right person? Reply “no thanks” and I’ll stop. · Unsubscribe"
}
}
}
GET /campaigns/{id}/steps
Get a campaign's sequence
Every step in order, with the same fields PUT takes — read, edit, write back.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/steps" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "step",
"number": 1,
"type": "email",
"wait_days": 0,
"subject": "Quick question about {{company}}",
"body": "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring SDRs — worth a short call?",
"variants": [
{
"subject": "{{first_name}}, a quick one",
"body": "Hi {{first_name}} — saw {{company}} is growing the SDR team…"
}
],
"due_days": 128,
"note": "…",
"signature": true,
"event": "…",
"within_days": 128,
"key": "…",
"path": "…",
"routes": {
"yes": "…",
"no": "…"
},
"move_on_accept": true
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
PUT /campaigns/{id}/steps
Replace a campaign's sequence
Replaces every step with these, in order. type is email (sent automatically), manual (an email a person sends from Tasks, prefilled) or call (a call task on any plan — you call from your own phone and log the outcome in Tasks; the calling add-on adds the in-app dialer). Personalise with {{first_name}}, {{company}}, {{title}} … or {{first_name|there}} for a fallback; a lead's custom fields are variables too, so {{email_1_body}} sends each lead their own copy. Blank lines make paragraphs; the mailbox signature is added unless signature is false. Up to 12 steps, 4 A/B variants each; the first step's wait_days is always 0.
Email campaigns only — a Multi Channel or LinkedIn sequence is edited in the app. On a sending campaign this changes what its remaining leads receive, and leads who had finished continue into steps added at the end, as saving in the app does.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
steps | array of object | required | The whole sequence, in order. |
Request
curl -s -X PUT "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/steps" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"steps":[{"type":"email","subject":"{{email_1_subject}}","body":"{{email_1_body}}"},{"type":"email","wait_days":3,"subject":"Re: {{email_1_subject}}","body":"{{email_2_body}}"},{"type":"call","wait_days":2,"subject":"Follow up on the emails","body":"Opener: I sent you a note about …","due_days":2}]}'
Response
{
"object": "list",
"data": [
{
"object": "step",
"number": 1,
"type": "email",
"wait_days": 0,
"subject": "Quick question about {{company}}",
"body": "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring SDRs — worth a short call?",
"variants": [
{
"subject": "{{first_name}}, a quick one",
"body": "Hi {{first_name}} — saw {{company}} is growing the SDR team…"
}
],
"due_days": 128,
"note": "…",
"signature": true,
"event": "…",
"within_days": 128,
"key": "…",
"path": "…",
"routes": {
"yes": "…",
"no": "…"
},
"move_on_accept": true
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
GET /campaigns/{id}/senders
Get a campaign's senders
The mailboxes it sends from. An empty list = every healthy sender in the workspace.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/senders" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "sender",
"id": "snd_2e10b4",
"email": "sam@outbound.acme.com",
"name": "Sam Reed",
"status": "ACTIVE"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
PUT /campaigns/{id}/senders
Set a campaign's senders
Choose the mailboxes it sends from (ids from GET /senders); an empty list = every healthy sender. Ids that aren't in your workspace are left out and listed in not_found.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Body
| Field | Type | Notes | |
|---|---|---|---|
sender_ids | array of string | required | Mailbox ids from GET /senders. |
Request
curl -s -X PUT "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/senders" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"sender_ids":["snd_2e10b4"]}'
Response
{
"object": "list",
"data": [
{
"object": "sender",
"id": "snd_2e10b4",
"email": "sam@outbound.acme.com",
"name": "Sam Reed",
"status": "ACTIVE"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
GET /campaigns/{id}/schedule
Get a campaign's schedule
When and how fast it sends: timezone, days, the sending window, the gap between emails and new leads a day.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/schedule" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
}
PATCH /campaigns/{id}/schedule
Change a campaign's schedule
Send only what changes; the rest keeps its value, as does every other setting. Tracking and UTM tags change with PATCH /campaigns/{id}; stop rules and the rest stay as set in the app. The window is read in the campaign's timezone — or each lead's own, with respect_lead_timezone.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Body
| Field | Type | Notes | |
|---|---|---|---|
timezone | string | optional | |
days | array of Mon · Tue · Wed · Thu · Fri · Sat · Sun | optional | |
window_from | string | optional | |
window_to | string | optional | |
gap_minutes | integer | optional | |
new_leads_per_day | integer | optional | |
respect_lead_timezone | boolean | optional | |
start_date | string | optional | YYYY-MM-DD, or "" to start straight away. |
Request
curl -s -X PATCH "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/schedule" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"timezone":"America/New_York","window_from":"08:30","window_to":"17:00","new_leads_per_day":60}'
Response
{
"object": "schedule",
"timezone": "America/New_York",
"days": [
"Mon",
"Tue",
"Wed",
"Thu",
"Fri"
],
"window_from": "09:00",
"window_to": "16:30",
"gap_minutes": 20,
"new_leads_per_day": 100,
"respect_lead_timezone": false,
"start_date": null
}
GET /campaigns/{id}/leads
List a campaign's leads
Who is in the campaign and where each is in the sequence, newest first.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
status | ACTIVE · PAUSED · REPLIED · BOUNCED · UNSUBSCRIBED · FINISHED | query | Filter by enrolment status. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/leads?status=ACTIVE" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "campaign_lead",
"status": "ACTIVE",
"stop_reason": null,
"step": 2,
"path": "…",
"waiting_on_task": false,
"last_sent_at": "2026-09-22T09:14:02.000Z",
"next_due_at": "2026-09-22T09:14:02.000Z",
"enrolled_at": "2026-09-22T09:14:02.000Z",
"lead": {
"object": "lead",
"id": "led_4b81e0",
"email": "priya@acme.com",
"first_name": "Priya",
"last_name": "Raman",
"company": "Acme",
"title": "Head of Operations",
"city": "Leeds",
"website": "acme.com",
"phone": "+44 7700 900123",
"linkedin_url": "https://www.linkedin.com/in/example-lead",
"status": "CONTACTED",
"tags": [
"Hot",
"Webinar"
],
"created_at": "2026-09-05T16:42:10.000Z"
}
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /campaigns/{id}/leads
Add leads to a campaign
Send leads (up to 2,000 per call) — they're saved as leads, deduped by email, into list_id or a new list — or just list_id to enrol a whole existing list. Only the people named are enrolled; others in a reused list aren't.
Like an import in the app: blocklisted and unsubscribed people are left out, anyone already in the campaign isn't added twice, new leads are added only while the workspace has room (the leads its plan keeps), and skip_active_elsewhere leaves out anyone still being emailed by another campaign. Enrolled leads start when the campaign is sending, within its schedule. Custom fields become {{variables}} for the copy.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
leads | array of object | optional | The people to add (or send list_id alone). |
list_id | string | optional | Save them into this existing list — or, without leads, enrol this whole list. |
list_name | string | optional | Name for the new list the leads go into (when there's no list_id). |
skip_active_elsewhere | boolean | optional | Leave out people still being emailed by another campaign. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/leads" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"leads":[{"email":"priya@acme.com","first_name":"Priya","company":"Acme","custom":{"email_1_subject":"Priya — the Leeds depot","email_1_body":"Congrats on opening the Leeds depot…"}},{"email":"tom@northwind.io","first_name":"Tom","company":"Northwind"}],"list_name":"Q4 — logistics"}'
Response
{
"object": "enrollment",
"campaign_id": "cmp_9f2a1c",
"list_id": "lst_9a12c4",
"imported": 180,
"updated": 14,
"skipped": 4,
"blocked": 2,
"enrolled": 192,
"in_list": null,
"skipped_active_elsewhere": 0,
"campaign_status": "SENDING",
"errors": [
{
"row": 7,
"email": "not-an-address",
"reason": "That isn't a valid email address."
}
]
}
DELETE /campaigns/{id}/leads/{lead_id}
Remove a lead from a campaign
Nothing more is sent to them from this campaign; the lead, their lists and what was already sent stay. An email campaign's enrolment is deleted (adding them again starts at step 1); a Multi Channel or LinkedIn campaign's is ended instead (ended: true), so the campaign can't add them back on its own.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
lead_id | string | required | The lead's id. |
Request
curl -s -X DELETE "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/leads/led_4b81e0" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign_lead",
"campaign_id": "cmp_9f2a1c",
"lead_id": "led_4b81e0",
"removed": true,
"ended": false,
"campaign_leads": 2399
}
GET /leads
List leads
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
status | NEW · CONTACTED · REPLIED · MEETING · WON · BOUNCED · UNSUBSCRIBED · BLOCKED | query | Filter by status. |
search | string | query | Case-insensitive match on email, company or name. |
email | string | query | One exact address — find a lead to update. |
list_id | string | query | Only the leads in this list. |
tag | string | query | Only leads with this tag (any case). Repeat it, or separate names with commas, for leads with any of them. |
Request
curl -s "https://mailfleet.co/api/v1/leads?status=CONTACTED" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "lead",
"id": "led_4b81e0",
"email": "priya@acme.com",
"first_name": "Priya",
"last_name": "Raman",
"company": "Acme",
"title": "Head of Operations",
"city": "Leeds",
"website": "acme.com",
"phone": "+44 7700 900123",
"linkedin_url": "https://www.linkedin.com/in/example-lead",
"status": "CONTACTED",
"tags": [
"Hot",
"Webinar"
],
"created_at": "2026-09-05T16:42:10.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /leads
Add leads
Add or update up to 2,000 leads without enrolling them anywhere — the same import as a CSV upload in the app: deduped by email across the workspace (an existing lead is updated and moved into the list), blocklisted addresses refused, and new leads added only up to the room the workspace has left (the leads its plan keeps; a full workspace adds none and says so in errors). Custom fields become {{variables}} for campaign copy. tags become lead tags — made where missing, only ever added (a re-import never takes one off); a name a reply mark uses ("Interested", "Out of office" …) isn't made and is listed in errors. To enrol them as well, use POST /campaigns/{id}/leads.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
leads | array of object | required | |
list_id | string | optional | Into this existing list. |
list_name | string | optional | Else a new list with this name (default "Added via API"). |
Request
curl -s -X POST "https://mailfleet.co/api/v1/leads" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"leads":[{"email":"priya@acme.com","first_name":"Priya","last_name":"Raman","company":"Acme","title":"Head of Operations"}],"list_id":"lst_9a12c4"}'
Response
{
"object": "import",
"list_id": "lst_9a12c4",
"list_name": "Added via API",
"imported": 180,
"updated": 14,
"skipped": 4,
"blocked": 2,
"custom_fields": [
"email_1_body"
],
"errors": [
{
"row": 7,
"email": "not-an-address",
"reason": "That isn't a valid email address."
}
]
}
GET /leads/{id}
Get a lead
The lead with its custom fields ({{variables}}), its list, and the campaigns it's in — status and step in each.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The lead's id. |
Request
curl -s "https://mailfleet.co/api/v1/leads/led_4b81e0" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "lead",
"id": "cmp_9f2a1c",
"email": "priya@acme.com",
"first_name": "Priya",
"last_name": "Raman",
"company": "Acme",
"title": "Head of Operations",
"city": "Leeds",
"website": "acme.com",
"phone": "…",
"linkedin_url": "…",
"status": "NEW",
"tags": [
"Hot",
"Webinar"
],
"created_at": "2026-09-22T09:14:02.000Z",
"list_id": "lst_9a12c4",
"timezone": "Europe/London",
"custom": {
"email_1_body": "Priya — congrats on the Leeds depot…"
},
"campaigns": [
{
"campaign_id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"campaign_status": "DRAFT",
"status": "ACTIVE",
"stop_reason": null,
"step": 128,
"last_sent_at": "2026-09-22T09:14:02.000Z",
"next_due_at": "2026-09-22T09:14:02.000Z"
}
]
}
PATCH /leads/{id}
Update a lead
Any field — an empty string clears it — and custom fields: a key set to "" is removed, others are added or replaced, the rest kept. Tags by name: add_tags (a new name becomes a tag) and remove_tags. The same edit as the lead panel in the app. An address another lead already uses is refused (409 email_taken); a tag name a reply mark uses, or a new tag past the workspace's 100, is refused (400 tags_refused) with nothing changed.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The lead's id. |
Body
| Field | Type | Notes | |
|---|---|---|---|
email | string | optional | |
first_name | string | optional | |
last_name | string | optional | |
company | string | optional | |
title | string | optional | |
website | string | optional | |
industry | string | optional | |
employee_count | string | optional | |
city | string | optional | |
country | string | optional | |
phone | string | optional | |
linkedin_url | string | optional | |
timezone | string | optional | IANA timezone (used when a campaign respects each lead's timezone). |
custom | object | optional | Keys of letters, digits and underscores. "" removes a key; others are added or replaced. |
add_tags | array of string | optional | Tag names to add (any case); a new name becomes a tag in the workspace's list. |
remove_tags | array of string | optional | Tag names to take off; a name that isn't one of the lead's tags is ignored. |
Request
curl -s -X PATCH "https://mailfleet.co/api/v1/leads/led_4b81e0" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"company":"Acme Logistics","custom":{"email_1_body":"Priya — congrats on the Leeds depot…"}}'
Response
{
"object": "lead",
"id": "cmp_9f2a1c",
"email": "priya@acme.com",
"first_name": "Priya",
"last_name": "Raman",
"company": "Acme",
"title": "Head of Operations",
"city": "Leeds",
"website": "acme.com",
"phone": "…",
"linkedin_url": "…",
"status": "NEW",
"tags": [
"Hot",
"Webinar"
],
"created_at": "2026-09-22T09:14:02.000Z",
"list_id": "lst_9a12c4",
"timezone": "Europe/London",
"custom": {
"email_1_body": "Priya — congrats on the Leeds depot…"
},
"campaigns": [
{
"campaign_id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"campaign_status": "DRAFT",
"status": "ACTIVE",
"stop_reason": null,
"step": 128,
"last_sent_at": "2026-09-22T09:14:02.000Z",
"next_due_at": "2026-09-22T09:14:02.000Z"
}
]
}
POST /leads/{id}/unsubscribe
Unsubscribe a lead
As if they clicked the unsubscribe link: marked Unsubscribed, stopped in every campaign still sending or paused, never enrolled again, and the lead.unsubscribed webhook fires. To block an address or a whole domain, use the blocklist.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The lead's id. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/leads/led_4b81e0/unsubscribe" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "lead",
"id": "led_4b81e0",
"email": "priya@acme.com",
"status": "UNSUBSCRIBED",
"campaigns_stopped": 1
}
GET /lists
List lead lists
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
Request
curl -s "https://mailfleet.co/api/v1/lists" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "list",
"id": "lst_9a12c4",
"name": "Med spas — Texas",
"leads": 412,
"created_at": "2026-09-22T09:14:02.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /lists
Create a list
An empty list; add leads to it with POST /leads and its list_id.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
name | string | required |
Request
curl -s -X POST "https://mailfleet.co/api/v1/lists" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"name":"Med spas — Texas"}'
Response
{
"object": "list",
"id": "lst_9a12c4",
"name": "Med spas — Texas",
"leads": 412,
"created_at": "2026-09-22T09:14:02.000Z"
}
GET /replies
List replies
Newest first. To sync your inbox, poll with received_after (the newest received_at you've seen) — or subscribe to the reply.received webhook instead.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
intent | INTERESTED · MEETING · QUESTION · NOT_NOW · NEUTRAL · UNSUBSCRIBE | query | Filter by detected intent. |
campaign_id | string | query | Filter by campaign. |
lead_id | string | query | One lead's replies. |
handled | boolean | query | true = handled only, false = still open. |
received_after | string (date-time) | query | Only replies received after this time (ISO 8601). |
Request
curl -s "https://mailfleet.co/api/v1/replies?intent=INTERESTED" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "reply",
"id": "rep_77c3a9",
"channel": "email",
"from_email": "priya@acme.com",
"from_name": "Priya Raman",
"subject": "Re: Quick question about Acme",
"preview": "Happy to take a look — how does Thursday suit?",
"intent": "INTERESTED",
"campaign_id": "cmp_9f2a1c",
"lead_id": "led_4b81e0",
"sender_id": "snd_2e10b4",
"handled": false,
"received_at": "2026-09-22T09:14:02.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
GET /replies/{id}
Get a conversation
The whole thread: every campaign email the lead was sent (step, delivery, when they opened or clicked), their replies and yours, in order — plus how it's classified, whether it's handled, and teammates' notes. Each message's text is the reply without the quoted history.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The reply's id. |
Request
curl -s "https://mailfleet.co/api/v1/replies/rep_77c3a9" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "conversation",
"id": "rep_77c3a9",
"channel": "email",
"subject": "Re: Quick question about Acme",
"class": "Interested",
"intent": "INTERESTED",
"tags": [
"hot"
],
"handled": false,
"read": true,
"starred": false,
"snoozed_until": null,
"received_at": "2026-09-22T09:14:02.000Z",
"sender": "sam@outbound.acme.com",
"lead": {
"id": "cmp_9f2a1c",
"email": "priya@acme.com",
"name": "Priya Raman",
"company": "Acme",
"title": "Head of Operations",
"phone": "…",
"status": "REPLIED"
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "…"
},
"messages": [
{
"direction": "in",
"kind": "reply_received",
"from": "priya@acme.com",
"to": "sam@outbound.acme.com",
"cc": [],
"bcc": [],
"files": [
{
"name": "site-photo.jpg",
"type": "image/jpeg",
"size": 284113,
"image": true
}
],
"subject": "Re: Quick question about Acme",
"text": "Happy to take a look — how does Thursday suit?",
"text_truncated": true,
"at": "2026-09-22T09:14:02.000Z",
"step": 128,
"campaign": "…",
"delivery": "…",
"opened_at": "2026-09-22T09:14:02.000Z",
"clicked_at": "2026-09-22T09:14:02.000Z"
}
],
"notes": [
{
"kind": "note",
"by": "…",
"at": "2026-09-22T09:14:02.000Z",
"body": "…",
"due_at": "2026-09-22T09:14:02.000Z",
"done": true
}
],
"not_shown": "…"
}
PATCH /replies/{id}
Mark a conversation
As the Replies inbox does. mark is "Mark lead as": Interested, Meeting request, Question, Not now, Not interested, OOO, Wrong person or Referral classify the thread (and start any subsequence waiting on that tag — OOO never starts one); Meeting booked and Won also move the lead's status (Won marks it handled); Unsubscribed stops the lead in every campaign. handled and read cover the whole conversation; tags are your own labels (the classification is set with mark).
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The reply's id. |
Body
| Field | Type | Notes | |
|---|---|---|---|
mark | Interested · Meeting request · Question · Not now · Not interested · OOO · Wrong person · Referral · Meeting booked · Won · Unsubscribed | optional | "Mark lead as" — the classification and what goes with it. |
handled | boolean | optional | Resolve (or reopen) the whole conversation. |
read | boolean | optional | |
tags | array of string | optional | Your own labels (replaces them). |
starred | boolean | optional | |
snoozed_until | string (date-time), nullable | optional | Out of the inbox until then (within a year); null wakes it. |
Request
curl -s -X PATCH "https://mailfleet.co/api/v1/replies/rep_77c3a9" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"mark":"Meeting booked","handled":true}'
Response
{
"object": "conversation",
"id": "rep_77c3a9",
"channel": "email",
"subject": "Re: Quick question about Acme",
"class": "Interested",
"intent": "INTERESTED",
"tags": [
"hot"
],
"handled": false,
"read": true,
"starred": false,
"snoozed_until": null,
"received_at": "2026-09-22T09:14:02.000Z",
"sender": "sam@outbound.acme.com",
"lead": {
"id": "cmp_9f2a1c",
"email": "priya@acme.com",
"name": "Priya Raman",
"company": "Acme",
"title": "Head of Operations",
"phone": "…",
"status": "REPLIED"
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound",
"status": "…"
},
"messages": [
{
"direction": "in",
"kind": "reply_received",
"from": "priya@acme.com",
"to": "sam@outbound.acme.com",
"cc": [],
"bcc": [],
"files": [
{
"name": "site-photo.jpg",
"type": "image/jpeg",
"size": 284113,
"image": true
}
],
"subject": "Re: Quick question about Acme",
"text": "Happy to take a look — how does Thursday suit?",
"text_truncated": true,
"at": "2026-09-22T09:14:02.000Z",
"step": 128,
"campaign": "…",
"delivery": "…",
"opened_at": "2026-09-22T09:14:02.000Z",
"clicked_at": "2026-09-22T09:14:02.000Z"
}
],
"notes": [
{
"kind": "note",
"by": "…",
"at": "2026-09-22T09:14:02.000Z",
"body": "…",
"due_at": "2026-09-22T09:14:02.000Z",
"done": true
}
],
"not_shown": "…"
}
POST /replies/{id}/reply
Reply to a lead
A real email, sent from the mailbox their message arrived on, in the same thread ("Re:" the subject) — exactly as replying in the Replies inbox: plain text (blank lines make paragraphs), the mailbox's CRM copy if it has one, a slot of its daily limit, and it goes out even while that mailbox is paused.
The same text can't go to the same conversation twice within a minute (409 duplicate_reply) — adding a cc doesn't make it a different reply; send an Idempotency-Key to retry safely. It doesn't mark the conversation handled — PATCH it for that.
cc and bcc copy up to 5 people in all, as the Cc / Bcc link in the Replies inbox does: everyone on the email sees who's in Cc; nobody sees who's in Bcc. The lead's own address and repeats are dropped; an address in both stays in cc. The whole reply is refused (400 cannot_send, nothing sent) for an address that isn't one, one of your own sending mailboxes, one on your blocklist, or a lead who bounced, unsubscribed or is blocked. A workspace can send 100 replies with copies in 24 hours (429 limit_reached); a reply without copies is never held by that. An address the mail server turns down doesn't stop the reply: it's listed in copies_refused.
If the lead unsubscribed, nothing is sent and the answer is 409 unsubscribed — send it again with confirm_unsubscribed: true to reply anyway. A lead who is Blocked, or whose address or domain is on your blocklist, is never replied to: 422 blocklisted, whatever the request says — remove them from the blocklist in MailFleet first.
Email conversations only. A LinkedIn conversation (channel: "linkedin") is answered from the Replies page in MailFleet, where the reply goes out as a LinkedIn message: here it gets 422 linkedin_conversation and nothing is sent.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The reply's id. |
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
body | string | required | The reply's text. |
cc | array of string (email) | optional | Copied, and seen by everyone on the email. Up to 5 across cc and bcc. |
bcc | array of string (email) | optional | Copied without anyone else seeing it. Up to 5 across cc and bcc. |
confirm_unsubscribed | boolean | optional | Reply even though the lead unsubscribed. Without it, a reply to an unsubscribed lead is refused with 409 unsubscribed. It doesn't override the blocklist. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/replies/rep_77c3a9/reply" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"body":"Thanks Priya — Thursday at 2pm works. I'll send an invite."}'
Response
{
"object": "message",
"direction": "out",
"reply_id": "rep_77c3a9",
"to": "priya@acme.com",
"cc": [
"jordan@acme.com"
],
"bcc": [],
"copies_refused": [
"old@acme.com"
],
"subject": "Re: Quick question about Acme",
"sender_id": "snd_2e10b4",
"sent_at": "2026-09-22T09:14:02.000Z"
}
GET /senders
List senders (mailboxes)
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
status | ACTIVE · UNVERIFIED · ERROR · PAUSED | query | Filter by status. |
Request
curl -s "https://mailfleet.co/api/v1/senders?status=ACTIVE" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "sender",
"id": "snd_2e10b4",
"email": "sam@outbound.acme.com",
"name": "Sam Reed",
"domain": "outbound.acme.com",
"provider": "google",
"status": "ACTIVE",
"health": 92,
"daily_limit": 40,
"sent_today": 22,
"gap_minutes": 20,
"warmup_enabled": true,
"has_imap": true,
"last_error": null,
"created_at": "2026-07-19T11:23:04.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
GET /stats
Workspace summary stats
Parameters
No parameters.
Request
curl -s "https://mailfleet.co/api/v1/stats" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "stats",
"campaigns": {
"total": 9,
"sending": 3
},
"senders": {
"total": 14,
"active": 11
},
"leads": {
"total": 2400
},
"replies": {
"total": 74,
"unhandled": 9
},
"emails": {
"sent_all_time": 41908,
"sent_today": 388,
"delivered_all_time": 128
},
"engagement": {
"replied": 74,
"interested": 21,
"bounced": 18,
"hard_bounced": 128,
"blocked": 128,
"leads_reached": 128,
"auto_replied": 128
}
}
GET /campaigns/{id}/stats
A campaign's numbers per day
One row per day from from to to (days with nothing included), with the range's totals. Each number is dated by when it happened, so a day's row is the same whatever range you ask for, and the days since the campaign started add up to its totals on GET /campaigns/{id}. Emails on the day they were sent — sent, delivered, bounced / hard_bounced and blocked (by what became of that email, so delivered + bounced + blocked = sent; a bounce that comes back later counts on its email's day). People on the day of their first time: leads_contacted (their first email from this campaign), opened (every recorded open counts, including the automatic ones mail-security scanners make on delivery), clicked (clicks in the first 5 minutes after sending — scanners — left out), replied (out-of-office and auto-replies left out), interested and auto_replied (people whose only answers were automatic). At most 366 days per request.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
from | string (date) | query | First day, YYYY-MM-DD, in timezone. Default: 29 days before to. |
to | string (date) | query | Last day, YYYY-MM-DD, included. Default: today. |
timezone | string | query | IANA timezone the days are counted in. Default: the campaign's own (its schedule's). |
granularity | day | query | day — one row per day. Default day. |
format | json · csv | query | json, or csv for a file of the rows. Default json. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/stats?from=2026-11-01" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"campaign_id": "cmp_9f2a1c",
"timezone": "America/New_York",
"granularity": "day",
"from": "2026-11-01",
"to": "2026-11-02",
"data": [
{
"date": "2026-11-01",
"sent": 120,
"delivered": 117,
"bounced": 3,
"hard_bounced": 3,
"blocked": 0,
"leads_contacted": 40,
"opened": 64,
"clicked": 9,
"replied": 4,
"interested": 1,
"auto_replied": 2
},
{
"date": "2026-11-02",
"sent": 98,
"delivered": 97,
"bounced": 1,
"hard_bounced": 1,
"blocked": 0,
"leads_contacted": 31,
"opened": 41,
"clicked": 4,
"replied": 3,
"interested": 2,
"auto_replied": 1
}
],
"totals": {
"sent": 218,
"delivered": 214,
"bounced": 4,
"hard_bounced": 4,
"blocked": 0,
"leads_contacted": 71,
"opened": 105,
"clicked": 13,
"replied": 7,
"interested": 3,
"auto_replied": 3
}
}
GET /campaigns/{id}/steps/stats
A campaign's numbers per step and A/B variant
One row per step and A/B variant — every email step's variants (none sent yet included), plus any other step, or a step or variant since removed (removed: true), that has emails. Over the emails sent from from to to, or all time when neither is given. sent, delivered, opened, clicked, bounced / hard_bounced and blocked count emails; replied, interested and auto_replied count people whose answer followed an email of that step and variant (the last one they got before answering) — as the campaign's Analytics tab counts them.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
from | string (date) | query | First day the emails were sent, YYYY-MM-DD, in timezone. Leave out from and to for all time. |
to | string (date) | query | Last day, included. Default: today (with from), and from defaults to 29 days before to. |
timezone | string | query | IANA timezone the dates are read in. Default: the campaign's own. |
format | json · csv | query | json, or csv for a file of the rows. Default json. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/steps/stats?from=2026-11-01" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"campaign_id": "cmp_9f2a1c",
"timezone": "America/New_York",
"from": "2026-11-01",
"to": "2026-11-30",
"data": [
{
"step_number": 1,
"variant": "A",
"type": "email",
"subject": "Quick question about {{company}}",
"removed": false,
"sent": 400,
"delivered": 391,
"opened": 210,
"clicked": 18,
"replied": 11,
"interested": 4,
"auto_replied": 6,
"bounced": 9,
"hard_bounced": 9,
"blocked": 0
},
{
"step_number": 1,
"variant": "B",
"type": "email",
"subject": "{{first_name}}, an idea for {{company}}",
"removed": false,
"sent": 400,
"delivered": 393,
"opened": 188,
"clicked": 12,
"replied": 7,
"interested": 2,
"auto_replied": 5,
"bounced": 7,
"hard_bounced": 7,
"blocked": 0
},
{
"step_number": 2,
"variant": "A",
"type": "email",
"subject": null,
"removed": false,
"sent": 352,
"delivered": 350,
"opened": 140,
"clicked": 6,
"replied": 5,
"interested": 1,
"auto_replied": 2,
"bounced": 2,
"hard_bounced": 2,
"blocked": 0
}
]
}
GET /campaigns/{id}/events
A campaign's events
Every event, oldest first, a page at a time — to backfill history, or to catch up after your webhook endpoint was down longer than the retry window. Read from what each email and reply recorded, the moments the webhooks fire on, so it covers emails sent before a webhook existed. Opens and clicks: the first on each email; when that one came in the first 5 minutes after sending (is_bot_suspected: true — mail-security scanners open and follow links on delivery), the person's own later open or click is listed too (is_bot_suspected: false), which is the one the stats count. Bounces: kind is bounced (a bad address) or blocked (refused as spam or on policy). Replies: the first real reply in each conversation (out-of-office and auto-replies aren't events), with reply.interested beside it when the conversation counts as interested now.
Page with cursor: send next_cursor from the last page, with the same type, until has_more is false. Event ids are stable, so a page fetched twice can be deduplicated.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
type | string | query | One or more, comma-separated: email.sent, email.opened, link.clicked, email.bounced, reply.received, reply.interested. Default: all. |
since | string (date-time) | query | Events at or after this time (ISO 8601). |
until | string (date-time) | query | Events before this time (ISO 8601). |
limit | integer | query | Page size, 1–1,000 (default 100). Default 100. |
cursor | string | query | next_cursor from the previous page. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/events?type=link.clicked" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"campaign_id": "cmp_9f2a1c",
"data": [
{
"object": "event",
"id": "evt_ZW1haWwub3BlbmVkfDhhMmYuLi46bw",
"type": "email.opened",
"occurred_at": "2026-11-03T14:02:41.000Z",
"campaign_id": "cmp_9f2a1c",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"custom": {
"crm_id": "0034x00001AbCdE"
}
},
"send_id": "8a2f…",
"reply_id": null,
"step_number": 1,
"variant": "A",
"is_bot_suspected": true
},
{
"object": "event",
"id": "evt_bGluay5jbGlja2VkfDhhMmYuLi46Y3A",
"type": "link.clicked",
"occurred_at": "2026-11-03T16:20:09.000Z",
"campaign_id": "cmp_9f2a1c",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"custom": {
"crm_id": "0034x00001AbCdE"
}
},
"send_id": "8a2f…",
"reply_id": null,
"step_number": 1,
"variant": "A",
"is_bot_suspected": false
},
{
"object": "event",
"id": "evt_cmVwbHkucmVjZWl2ZWR8cmVwXzc3YzNhOQ",
"type": "reply.received",
"occurred_at": "2026-11-04T09:14:02.000Z",
"campaign_id": "cmp_9f2a1c",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"custom": {
"crm_id": "0034x00001AbCdE"
}
},
"send_id": null,
"reply_id": "rep_77c3a9",
"step_number": 1,
"variant": "A"
}
],
"has_more": true,
"next_cursor": "WzE3NjIwMDAwMDAwMDAsMiwiOGEyZi4uLjpjIl0"
}
GET /campaigns/{id}/export
Export a campaign's leads with their engagement
Everyone in the campaign, one row each, in a single streamed response — no paging, however big the campaign. Each row: the lead (lead_id, the standard fields, custom fields — columns in CSV, a custom object in JSON — and tags), where they are in the campaign, and their engagement, counted as the campaign's stats are: emails sent and when, delivered / hard_bounced / blocked, opened and clicked (with when first), replied (when, its category and the step it answered), interested, auto_replied and unsubscribed. csv (the default) opens in a spreadsheet; json is one document { object, campaign_id, data: [...] }; ndjson is one JSON object per line, for loading into a warehouse.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The campaign's id. |
format | csv · json · ndjson | query | csv, json or ndjson. Default csv. |
Request
curl -s "https://mailfleet.co/api/v1/campaigns/cmp_9f2a1c/export?format=csv" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"campaign_id": "cmp_9f2a1c",
"data": [
{
"lead_id": "led_4b81e0",
"email": "priya@acme.com",
"first_name": "Priya",
"last_name": "Raman",
"company": "Acme",
"title": "Head of Operations",
"custom": {
"crm_id": "0034x00001AbCdE"
},
"tags": [
"Webinar"
],
"status": "REPLIED",
"step": 2,
"enrolled_at": "2026-11-01T08:02:11.000Z",
"next_email_at": null,
"stop_reason": null,
"stopped_at": null,
"lead_status": "REPLIED",
"emails_sent": 1,
"first_sent_at": "2026-11-01T14:31:07.000Z",
"last_sent_at": "2026-11-01T14:31:07.000Z",
"last_email_step": 1,
"delivered": true,
"hard_bounced": false,
"blocked": false,
"opened": true,
"first_opened_at": "2026-11-01T14:31:09.000Z",
"clicked": true,
"first_clicked_at": "2026-11-01T16:20:09.000Z",
"replied": true,
"replied_at": "2026-11-02T09:14:02.000Z",
"reply_category": "Interested",
"replied_to_step": 1,
"interested": true,
"auto_replied": false,
"unsubscribed": false
}
]
}
GET /blocklist
List the blocklist
Addresses and whole domains that are never contacted, newest first.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
kind | email · domain | query | Only addresses or only domains. |
Request
curl -s "https://mailfleet.co/api/v1/blocklist?kind=domain" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "blocklist_entry",
"id": "cmp_9f2a1c",
"value": "competitor.com",
"kind": "domain",
"note": "api",
"created_at": "2026-09-22T09:14:02.000Z"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /blocklist
Block addresses or domains
As Settings → Blocklist does: leads already in the workspace that match are marked Blocked and stopped in every campaign, and a blocked address is never imported or enrolled again. A URL counts as its domain. Up to 20,000 entries per call.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
entries | array of string | required | |
note | string | optional | Where they came from (shown in Settings). |
Request
curl -s -X POST "https://mailfleet.co/api/v1/blocklist" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"entries":["jo@competitor.com","competitor.com"]}'
Response
{
"object": "blocklist_result",
"added": 2,
"already_blocked": 0,
"invalid": [],
"leads_blocked": 1
}
GET /webhooks
List webhooks
Your endpoints and the events each gets. Signing secrets aren't listed — each is shown once, when it's created.
Parameters
No parameters.
Request
curl -s "https://mailfleet.co/api/v1/webhooks" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "webhook",
"id": "whk_1d4f07",
"url": "https://your-app.com/hooks/mailfleet",
"events": [
"reply.received",
"reply.interested"
],
"active": true,
"last_status": 200,
"last_fired_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"secret": "whsec_…"
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true
}
}
POST /webhooks
Create a webhook
A signed POST to your URL the moment each chosen event happens (X-MailFleet-Signature: HMAC-SHA256 of the raw body with the secret), retried for 24 hours if your endpoint is down. Every body is { id, event, workspaceId, occurredAt, data }, with the lead and its custom fields in data.lead — each event's body is under Webhook events below. The secret is in this response only — keep it. Up to 25 webhooks per workspace.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
Idempotency-Key | string | header | Optional: a unique key (a UUID) so a retry of this request replays the first response instead of doing it twice. Kept for 24 hours. |
Body
| Field | Type | Notes | |
|---|---|---|---|
url | string (uri) | required | |
events | array of email.sent · email.opened · link.clicked · reply.received · reply.interested · reply.tagged · email.bounced · lead.unsubscribed · lead.enriched · deal.created · deal.stage_changed · deal.won · deal.lost | required |
Request
curl -s -X POST "https://mailfleet.co/api/v1/webhooks" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"url":"https://your-app.com/hooks/mailfleet","events":["reply.received","reply.interested"]}'
Response
{
"object": "webhook",
"id": "whk_1d4f07",
"url": "https://your-app.com/hooks/mailfleet",
"events": [
"reply.received",
"reply.interested"
],
"active": true,
"last_status": 200,
"last_fired_at": "2026-09-22T09:14:02.000Z",
"created_at": "2026-09-22T09:14:02.000Z",
"secret": "whsec_…"
}
DELETE /webhooks/{id}
Delete a webhook
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required | The webhook's id. |
Request
curl -s -X DELETE "https://mailfleet.co/api/v1/webhooks/whk_1d4f07" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "campaign",
"id": "cmp_9f2a1c",
"deleted": true
}
GET /leaddb/search
Search the Lead Database
Search 53M people by title, seniority, location, industry and company size. Free — only a reveal costs anything.
Addresses come back masked. /leaddb/reveal is the only path to a full address. Array filters repeat the key: ?seniority=vp&seniority=head.
pagination.capped is true when total is a floor rather than a count: more than 10,000 people match, or (with a category filter) the search was too broad to count in time and total is just past the page you asked for. Use has_more to page either way. Rate limit: 60 requests/minute.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
limit | integer | query | Page size, 1–100 (default 25). Default 25. |
offset | integer | query | Number of items to skip (default 0). Default 0. |
q | string | query | Free text across name, title and company. |
title | string | query | Single job-title match. |
titles | array of string | query | Any-of job titles (repeat the key, or comma-separate). |
exclude_titles | array of string | query | None-of job titles. |
similar_titles | boolean | query | Expand each title to its common variants. |
seniority | array of c_suite · founder · owner · partner · vp · head · director · manager · senior · entry · intern | query | Any-of seniority bands. |
countries | array of string | query | Any-of countries. |
states | array of string | query | Any-of states or regions. |
industries | array of string | query | Any-of industries. |
employees_min | integer | query | Company size: the smallest number of employees, inclusive. A whole number from 1 to 1,000,000 (digits, optionally with thousands commas: 1,000); anything else is a 400 invalid_filter. Use it with employees_max for a range (5 and 50 = companies with 5 to 50 employees), or alone for that many or more. Companies with no size on record are left out of any size filter. |
employees_max | integer | query | Company size: the largest number of employees, inclusive. A whole number from 1 to 1,000,000; alone, it means 1 up to that many. If it is smaller than employees_min, the two are swapped. |
employees | array of 1-10 · 11-50 · 51-200 · 201-1000 · 1001+ | query | Deprecated. Any-of company-size bands — 1-10, 11-50, 51-200, 201-1000, 1001+ (send the plus as %2B; an unencoded + is read as a space, and 1001 alone is taken as 1001+). Repeat the key, or comma-separate. Any other value is a 400 invalid_filter. Use employees_min / employees_max instead; given together with them, both apply. |
email | any · has · verified | query | Require an address, or a verified one. |
phone | boolean | query | Only people with a phone number on file. |
saved | all · saved · new | query | All people, only ones you have already acquired, or only new ones. |
Request
curl -s "https://mailfleet.co/api/v1/leaddb/search?q=Priya%20Raman" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "list",
"data": [
{
"object": "leaddb_person",
"id": "48210337",
"full_name": "Priya Raman",
"first_name": "Priya",
"last_name": "Raman",
"title": "Head of Operations",
"seniority": "head",
"email_masked": "p****@acme.com",
"email_status": "verified",
"email_corporate": true,
"email_check": "valid",
"email_checked_at": "2026-09-19T04:11:20.000Z",
"has_phone": true,
"linkedin_url": "https://www.linkedin.com/in/example-lead",
"city": "Leeds",
"state": "West Yorkshire",
"country": "United Kingdom",
"company": {
"name": "Acme",
"domain": "acme.com",
"industry": "Logistics",
"employees": 120
},
"acquired": false
}
],
"pagination": {
"total": 214,
"limit": 25,
"offset": 0,
"has_more": true,
"capped": false,
"count_cap": 10000
}
}
POST /leaddb/reveal
Reveal a person's email address
The only endpoint that returns an unmasked address, and the only one that spends anything.
You pay once per person, ever. Revealing someone you have already acquired returns charged: false and costs nothing. A charged reveal spends one unit of the monthly Lead Database allowance (and one lead credit on a workspace still on monthly lead credits). Nothing is charged unless an address is handed over.
A reveal saves the person to your leads. The lead takes one place in your workspace like any other, in a list named "Revealed from Lead Database" (or the add_to_list list), with the same fields an add brings; deleting it frees the place, and revealing them again later is free of the allowance and saves them again. So a reveal needs one free place, unless the person is already one of your leads (matched by email): with none, it answers 402 lead_storage_full and charges nothing. saved_to_leads, lead_list and lead_id say where they are. If the address was handed over but the lead couldn't be written (or the address would bounce, or is blocklisted), saved_to_leads is false and save_note says why. A workspace still on monthly lead credits keeps nothing from a reveal, as before — use add_to_list.
The address is verified live at reveal time (if it was checked in the last 24 hours, you get that answer straight away). One person per call. Rate limit: 60 requests/minute.
Parameters
No parameters.
Body
| Field | Type | Notes | |
|---|---|---|---|
person_id | string | required | The id of a person from /leaddb/search. |
add_to_list | string | optional | The list the person is saved into as a lead — the id of one of your lead lists, or new for a fresh one — instead of "Revealed from Lead Database". On a workspace still on monthly lead credits, which keeps nothing from a reveal, this is what adds them. Free: the import skips anyone already acquired. |
Request
curl -s -X POST "https://mailfleet.co/api/v1/leaddb/reveal" \
-H "Authorization: Bearer sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"person_id":"48210337"}'
Response
{
"object": "leaddb_reveal",
"person_id": "48210337",
"email": "priya.raman@acme.com",
"verification": {
"outcome": "valid",
"code": null,
"checked_at": "2026-09-22T09:14:02.000Z",
"cached": false
},
"charged": true,
"lead_id": "led_4b81e0",
"saved_to_leads": true,
"lead_list": {
"id": "cmp_9f2a1c",
"name": "Revealed from Lead Database"
},
"save_note": "…",
"quota": {
"used": 1841,
"cap": 5000,
"remaining": 3159,
"period": "2026-09"
}
}
POST /leads/{id}/enrich
Find a lead's mobile number
Reveal the lead's own mobile or direct line through your Apollo key (Settings → Integrations). The company switchboard is never substituted.
Asynchronous. Apollo sends the number back a little later, so this answers 202 pending. Subscribe to the lead.enriched webhook rather than polling — it fires the moment the reveal settles, found or not.
Spends no MailFleet credit; Apollo bills your own key. Limits: 30/minute and 500/day per workspace, so a runaway script cannot drain your Apollo balance.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required |
Request
curl -s -X POST "https://mailfleet.co/api/v1/leads/led_4b81e0/enrich" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "enrichment",
"id": "enr_71c0aa",
"lead_id": "led_4b81e0",
"status": "pending"
}
GET /leads/{id}/enrich
Check an enrichment
The lead's current number and the state of its most recent enrichment. status is null when the lead has never been enriched.
Parameters
| Parameter | Type | In | Notes |
|---|---|---|---|
id | string | required |
Request
curl -s "https://mailfleet.co/api/v1/leads/led_4b81e0/enrich" \
-H "Authorization: Bearer sk_live_your_key"
Response
{
"object": "enrichment",
"id": "enr_71c0aa",
"lead_id": "led_4b81e0",
"status": "done",
"phone": "+44 7700 900123",
"updated_at": "2026-09-22T09:16:41.000Z"
}
Webhook events
Every event is a signed JSON POST to your URL: { id, event, workspaceId, occurredAt, data }. id is the delivery id — a retry sends the same bytes with the same id, so you can deduplicate. data carries lead (id, email, name, company, title, status, and custom — the lead's custom fields as imported, so a CRM id travels with every event) whenever the event is about a lead, and campaign (id, name) whenever it is about a campaign. Headers: X-MailFleet-Event, X-MailFleet-Delivery (= id), X-MailFleet-Attempt, X-MailFleet-Timestamp and X-MailFleet-Signature — the hex HMAC-SHA256 of the raw body with your webhook's secret. An endpoint that doesn't answer 2xx is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours; missed events can also be read back from GET /campaigns/{id}/events.
email.sent Email sent
A campaign email went out. step is the step's position from 0 (step 1 is 0). resendOf is set when it repeats an earlier email word for word after an out-of-office.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "email.sent",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 0,
"sendId": "3f6e1a4c-…",
"subject": "Quick question about Acme",
"fromEmail": "sam@outbound.acme.com",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
email.opened Email opened
The first open recorded on an email. step is the email's step from 0, as in email.sent. isBotSuspected is true when it came in the first 5 minutes after sending — usually a mail-security scanner on delivery, not the person.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "email.opened",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 1,
"sendId": "3f6e1a4c-…",
"isBotSuspected": false,
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
link.clicked Link clicked
The first click on a link in an email (an instant burst with the open — a scanner — isn't one). step is the email's step from 0, as in email.sent. url is where it went. isBotSuspected is true in the first 5 minutes after sending; the campaign's stats leave those clicks out.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "link.clicked",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 1,
"sendId": "3f6e1a4c-…",
"url": "https://acme.com/pricing?utm_source=outbound",
"isBotSuspected": false,
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
reply.received Reply received
The first real reply in a conversation (out-of-office and auto-replies don't fire it). intent is what the reply reads as: INTERESTED, MEETING, QUESTION, NOT_NOW, NEUTRAL or UNSUBSCRIBE. step is the email they answered, from 0 as in email.sent: the last one the campaign sent them before the reply (null when there's none). channel is "linkedin" for a LinkedIn message, which has no step.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "reply.received",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 1,
"fromEmail": "priya@acme.com",
"subject": "Re: Quick question about Acme",
"preview": "Happy to take a look — how does Thursday suit?",
"intent": "INTERESTED",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
reply.interested Reply — interested
Fires with reply.received when the reply reads as interested or asks for a meeting. The same body.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "reply.interested",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 1,
"fromEmail": "priya@acme.com",
"subject": "Re: Quick question about Acme",
"preview": "Happy to take a look — how does Thursday suit?",
"intent": "INTERESTED",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
reply.tagged Reply tagged (Interested, Meeting request, Question…)
A conversation was tagged — by the reply tagger or by hand: Interested, Meeting request, Question, Not now … replyId is the conversation (GET /replies/{id}).
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "reply.tagged",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"replyId": "rep_77c3a9",
"subject": "Re: Quick question about Acme",
"tag": "Meeting request",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
email.bounced Email bounced
An email didn't arrive. kind is "blocked" when it was refused as spam or on policy (the address is fine); "bounced", or left out, for a bad address. step (from 0) when known.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "email.bounced",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"campaignId": "cmp_9f2a1c",
"step": 1,
"kind": "bounced",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
lead.unsubscribed Lead unsubscribed
Someone opted out: the unsubscribe link, a reply saying so (then with the reply's fields), or by hand in the app.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "lead.unsubscribed",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
}
}
}
lead.enriched Phone enrichment finished (found, or not found)
A phone enrichment finished (POST /leads/{id}/enrich). status is "done" with the phone, or "not_found".
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "lead.enriched",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"enrichmentId": "enr_71c0aa",
"status": "done",
"phone": "+44 7700 900123",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
}
}
}
deal.created Deal created
A deal was created. value is whole units of currency; status is open, won or lost. leadId is its first contact's lead, when it has one.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "deal.created",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"dealId": "dl_5c2e90",
"name": "Acme — pilot",
"value": 25000,
"currency": "USD",
"stage": "meeting",
"status": "open",
"lostReason": null,
"ownerId": null,
"closeDate": "2026-12-15",
"campaignId": "cmp_9f2a1c",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
deal.stage_changed Deal moved to another stage
A deal moved to another stage. The deal as it is now, as in deal.created.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "deal.stage_changed",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"dealId": "dl_5c2e90",
"name": "Acme — pilot",
"value": 25000,
"currency": "USD",
"stage": "proposal",
"status": "open",
"lostReason": null,
"ownerId": null,
"closeDate": "2026-12-15",
"campaignId": "cmp_9f2a1c",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
deal.won Deal won
A deal was marked won. The deal as in deal.created.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "deal.won",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"dealId": "dl_5c2e90",
"name": "Acme — pilot",
"value": 25000,
"currency": "USD",
"stage": "negotiation",
"status": "won",
"lostReason": null,
"ownerId": null,
"closeDate": "2026-12-15",
"campaignId": "cmp_9f2a1c",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
deal.lost Deal lost
A deal was marked lost, with its lostReason. The deal as in deal.created.
{
"id": "b6c1f2de-6a0e-4c1b-9f3e-2d8a7c5e4b10",
"event": "deal.lost",
"workspaceId": "ws_3c9d1e",
"occurredAt": "2026-11-12T15:04:12.000Z",
"data": {
"dealId": "dl_5c2e90",
"name": "Acme — pilot",
"value": 25000,
"currency": "USD",
"stage": "proposal",
"status": "lost",
"lostReason": "Price",
"ownerId": null,
"closeDate": null,
"campaignId": "cmp_9f2a1c",
"leadId": "led_4b81e0",
"leadEmail": "priya@acme.com",
"lead": {
"id": "led_4b81e0",
"email": "priya@acme.com",
"firstName": "Priya",
"lastName": "Raman",
"company": "Acme",
"title": "Head of Operations",
"status": "CONTACTED",
"custom": {
"crm_id": "0034x00001AbCdE",
"region": "EMEA"
}
},
"campaign": {
"id": "cmp_9f2a1c",
"name": "Acme — Q4 outbound"
}
}
}
Objects
Campaign
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
name | string | |
status | DRAFT · SENDING · PAUSED · FINISHED | |
stats | objectleads sent opened clicked replied interested bounced skipped delivered hard_bounced blocked leads_reached auto_replied | Counted from the campaign's emails and replies. sent, delivered, bounced, hard_bounced and blocked count emails; opened, clicked, replied and interested count people, out of leads_reached. Every recorded open counts, including the automatic ones mail-security scanners make on delivery; clicks in the first 5 minutes after sending are left out (scanners follow every link on delivery), and so are out-of-office and auto-replies. |
started_at | string (date-time), nullable | |
created_at | string (date-time) |
Sender
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
email | string | |
name | string | |
domain | string | |
provider | string | |
status | ACTIVE · UNVERIFIED · ERROR · PAUSED | |
health | integer | 0–100 reputation score. |
daily_limit | integer | |
sent_today | integer | |
gap_minutes | integer | |
warmup_enabled | boolean | |
has_imap | boolean | |
last_error | string, nullable | |
created_at | string (date-time) |
Lead
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
email | string | |
first_name | string, nullable | |
last_name | string, nullable | |
company | string, nullable | |
title | string, nullable | |
city | string, nullable | |
website | string, nullable | |
phone | string, nullable | Filled in by /leads/{id}/enrich, or from your import. |
linkedin_url | string, nullable | |
status | NEW · CONTACTED · REPLIED · MEETING · WON · BOUNCED · UNSUBSCRIBED · BLOCKED | |
tags | array of string | The lead's tags (Settings → Lead Tags in the app), A–Z. Labels only: they never change what's sent. |
created_at | string (date-time) |
Reply
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
channel | email · linkedin | email, or linkedin: a LinkedIn message, answered from the Replies page in MailFleet (the API sends email replies only). |
from_email | string | |
from_name | string, nullable | |
subject | string, nullable | |
preview | string, nullable | |
intent | INTERESTED · MEETING · QUESTION · NOT_NOW · NEUTRAL · UNSUBSCRIBE | |
campaign_id | string, nullable | |
lead_id | string, nullable | |
sender_id | string, nullable | |
handled | boolean | |
received_at | string (date-time) |
CampaignDetail
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
name | string | |
status | DRAFT · SENDING · PAUSED · FINISHED | |
stats | objectleads sent opened clicked replied interested bounced skipped delivered hard_bounced blocked leads_reached auto_replied | Counted from the campaign's emails and replies. sent, delivered, bounced, hard_bounced and blocked count emails; opened, clicked, replied and interested count people, out of leads_reached. Every recorded open counts, including the automatic ones mail-security scanners make on delivery; clicks in the first 5 minutes after sending are left out (scanners follow every link on delivery), and so are out-of-office and auto-replies. |
started_at | string (date-time), nullable | |
created_at | string (date-time) | |
type | email · multichannel · linkedin · subsequence | email campaigns are the ones the API writes sequences for. |
step_count | integer | Steps in the sequence. |
sender_ids | array of string | The mailboxes it sends from. Empty = every healthy sender. |
schedule | objectobject timezone days window_from window_to gap_minutes new_leads_per_day respect_lead_timezone start_date | |
settings | objecttracking utm unsubscribe_line | Tracking, UTM tags and the unsubscribe line. Change them with PATCH /campaigns/{id}. |
CampaignSettings
| Field | Type | Notes |
|---|---|---|
tracking | objectopen click plain_text tracking_domains | What its emails carry: open is a tracking pixel, click is tracked links. A plain-text email carries neither. |
utm | object, nullablesource medium campaign content term | The UTM tags added to every link, or null when off. A value may hold {{step_number}} and {{variant}}. |
unsubscribe_line | object, nullabletext reads | The line after each email's signature, or null when off (a new campaign's default): its sentence ("" = the Unsubscribe link alone) and the line as it reads. The one-click List-Unsubscribe header goes on every email either way. |
CampaignSettingsInput
| Field | Type | Notes |
|---|---|---|
tracking | objectopen click plain_text | |
utm | object, nullablesource medium campaign content term | null turns the tags off. Each value up to 100 characters; null or "" clears it. |
unsubscribe_line | object, nullabletext | An object turns the line on; null turns it off. text: the sentence before the Unsubscribe link, up to 300 characters ("" = the link alone; left out keeps the one set). |
DailyStats
| Field | Type | Notes |
|---|---|---|
date | string (date) | |
sent | integer | Emails sent that day. |
delivered | integer | Of those, delivered (not bounced or blocked). |
bounced | integer | Of those, hard-bounced (bad address). Same as hard_bounced. |
hard_bounced | integer | |
blocked | integer | Of those, refused as spam or on policy — never in bounced. |
leads_contacted | integer | People sent their first email from this campaign that day. |
opened | integer | People who first opened that day. |
clicked | integer | People who first clicked that day (5+ minutes after sending). |
replied | integer | People whose first real reply arrived that day. |
interested | integer | People whose first interested reply arrived that day. |
auto_replied | integer | People whose first automatic answer arrived that day — only people who never replied themselves. |
StepStats
| Field | Type | Notes |
|---|---|---|
step_number | integer, nullable | From 1, as in GET /campaigns/{id}/steps. null: a Multi Channel step since removed. |
variant | string | A/B variant: A (the step's own copy), B, C … |
type | string | email, manual … |
subject | string, nullable | The step's (or variant's) subject template. |
removed | boolean | A step or variant no longer in the sequence that still has emails. |
sent | integer | |
delivered | integer | |
opened | integer | Emails opened (any recorded open). |
clicked | integer | Emails clicked 5+ minutes after sending. |
replied | integer | People whose real reply followed this step and variant. |
interested | integer | |
auto_replied | integer | |
bounced | integer | |
hard_bounced | integer | |
blocked | integer |
Event
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | Stable: the same event always has the same id. |
type | email.sent · email.opened · link.clicked · email.bounced · reply.received · reply.interested | |
occurred_at | string (date-time) | |
campaign_id | string | |
lead | objectid email custom | id, email and the lead's custom fields. |
send_id | string, nullable | The email (email.* and link.clicked). |
reply_id | string, nullable | The conversation (reply.*) — GET /replies/{id}. |
step_number | integer, nullable | |
variant | string, nullable | |
is_bot_suspected | boolean | email.opened and link.clicked: in the first 5 minutes after sending, when mail-security scanners open and follow links. |
kind | bounced · blocked | email.bounced only. |
ExportRow
| Field | Type | Notes |
|---|---|---|
lead_id | string | |
email | string | |
first_name | string, nullable | |
last_name | string, nullable | |
company | string, nullable | |
title | string, nullable | |
custom | object | The lead's custom fields, as imported. |
tags | array of string | |
status | string | Their enrolment: ACTIVE, PAUSED, REPLIED, BOUNCED, UNSUBSCRIBED or FINISHED. |
step | integer | The step they're on, from 1 (past the last once finished). |
enrolled_at | string (date-time) | |
next_email_at | string (date-time), nullable | |
stop_reason | string, nullable | |
stopped_at | string (date-time), nullable | |
lead_status | string, nullable | |
emails_sent | integer | |
first_sent_at | string (date-time), nullable | |
last_sent_at | string (date-time), nullable | |
last_email_step | integer, nullable | |
delivered | boolean | At least one email arrived. |
hard_bounced | boolean | |
blocked | boolean | |
opened | boolean | |
first_opened_at | string (date-time), nullable | |
clicked | boolean | Clicked 5+ minutes after sending. |
first_clicked_at | string (date-time), nullable | |
replied | boolean | A real reply (out-of-office and auto-replies left out). |
replied_at | string (date-time), nullable | |
reply_category | string, nullable | |
replied_to_step | integer, nullable | |
interested | boolean | |
auto_replied | boolean | |
unsubscribed | boolean |
Schedule
| Field | Type | Notes |
|---|---|---|
object | string | |
timezone | string | IANA timezone the window is read in. |
days | array of Mon · Tue · Wed · Thu · Fri · Sat · Sun | Days it sends on. |
window_from | string | Start of the sending window, 24-hour HH:MM. |
window_to | string | End of the sending window. |
gap_minutes | integer | Minutes between two emails from the same mailbox (1–240). |
new_leads_per_day | integer | First emails a day, across the campaign. |
respect_lead_timezone | boolean | Read the window in each lead's own timezone (their timezone field), else the campaign's. |
start_date | string, nullable | YYYY-MM-DD; null = start straight away. |
ScheduleInput
| Field | Type | Notes |
|---|---|---|
timezone | string | |
days | array of Mon · Tue · Wed · Thu · Fri · Sat · Sun | |
window_from | string | |
window_to | string | |
gap_minutes | integer | |
new_leads_per_day | integer | |
respect_lead_timezone | boolean | |
start_date | string | YYYY-MM-DD, or "" to start straight away. |
Step
| Field | Type | Notes |
|---|---|---|
object | string | |
number | integer | Position in the sequence, from 1. |
type | email · manual · call | Multi Channel sequences also have linkedin_* and condition steps. |
wait_days | integer | Days after the previous step (0 for the first). |
subject | string | Email subject, or the call objective. |
body | string | Email body or call script. |
variants | array of object | A/B variants (up to 4). |
due_days | integer, nullable | manual/call: days the person has to do the task. |
note | string | manual/call: an internal note shown with the task. |
signature | boolean | email/manual: whether the sending mailbox's signature is added. |
event | string, nullable | condition: what it checks — `Opened`, `Clicked a link`, `Accepted connection` (or `Replied` on a stop-when condition). |
within_days | integer | condition: how many days it waits for that. |
key | string, nullable | Multi Channel paths: the step's stable id (kept when steps are reordered or edited). |
path | string | Multi Channel paths: the path this step is on (`main` is where everyone starts). |
routes | objectyes no | Multi Channel paths, a split: where each answer goes — `yes` and `no`, each `next` (carry on), `end` (the sequence ends) or `{ "path": "…" }`. |
move_on_accept | boolean | Multi Channel paths, an "accepted your invite?" split: someone on its Not connected path who accepts later moves to its Connected answer. |
StepInput
| Field | Type | Notes |
|---|---|---|
type | email · manual · call | Default email. call works on any plan (the calling add-on adds the in-app dialer). |
subject | string | Email subject, or the call objective. |
body | string | Required for email and manual steps. |
wait_days | integer | Days after the previous step (default 3; always 0 for the first). |
due_days | integer | manual/call: days to do the task (default 2). |
note | string | manual/call: an internal note. |
variants | array of object | |
signature | boolean | email and manual steps: add the sending mailbox's signature. Default true. |
Variant
| Field | Type | Notes |
|---|---|---|
subject | string | |
body | string |
CampaignSender
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
email | string | |
name | string | |
status | ACTIVE · UNVERIFIED · ERROR · PAUSED |
CampaignLead
| Field | Type | Notes |
|---|---|---|
object | string | |
status | ACTIVE · PAUSED · REPLIED · BOUNCED · UNSUBSCRIBED · FINISHED | |
stop_reason | replied_directly_on_linkedin | Why a stopped enrolment stopped, when its status alone doesn't say. replied_directly_on_linkedin: you wrote to them on LinkedIn yourself, so the campaign stopped for them — status stays REPLIED, and it isn't counted as a reply from them. Otherwise null. |
step | integer | The step they're on, from 1 (past the last step once finished). |
path | string | Multi Channel paths only: the path they're on, or finished on (absent while that is Main). |
waiting_on_task | boolean | Parked on a manual or call task until someone completes it. |
last_sent_at | string (date-time), nullable | |
next_due_at | string (date-time), nullable | When their next step is due. |
enrolled_at | string (date-time) | |
lead | objectobject id email first_name last_name company title city website phone linkedin_url status tags created_at |
CampaignLeadRemoved
| Field | Type | Notes |
|---|---|---|
object | string | |
campaign_id | string | |
lead_id | string | |
removed | boolean | |
ended | boolean | A Multi Channel or LinkedIn enrolment is ended rather than deleted. |
campaign_leads | integer | People left in the campaign. |
LeadInput
| Field | Type | Notes |
|---|---|---|
email | string | |
first_name | string | |
last_name | string | |
company | string | |
title | string | |
city | string | |
country | string | |
website | string | |
industry | string | |
phone | string | |
linkedin_url | string | |
custom | object | Extra fields, each a {{variable}} in the copy ("Email 1 Body" becomes email_1_body). |
tags | array of string | Lead tags by name — made where missing, only ever added. |
LeadEdit
| Field | Type | Notes |
|---|---|---|
email | string | |
first_name | string | |
last_name | string | |
company | string | |
title | string | |
website | string | |
industry | string | |
employee_count | string | |
city | string | |
country | string | |
phone | string | |
linkedin_url | string | |
timezone | string | IANA timezone (used when a campaign respects each lead's timezone). |
custom | object | Keys of letters, digits and underscores. "" removes a key; others are added or replaced. |
add_tags | array of string | Tag names to add (any case); a new name becomes a tag in the workspace's list. |
remove_tags | array of string | Tag names to take off; a name that isn't one of the lead's tags is ignored. |
LeadDetail
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
email | string | |
first_name | string, nullable | |
last_name | string, nullable | |
company | string, nullable | |
title | string, nullable | |
city | string, nullable | |
website | string, nullable | |
phone | string, nullable | Filled in by /leads/{id}/enrich, or from your import. |
linkedin_url | string, nullable | |
status | NEW · CONTACTED · REPLIED · MEETING · WON · BOUNCED · UNSUBSCRIBED · BLOCKED | |
tags | array of string | The lead's tags (Settings → Lead Tags in the app), A–Z. Labels only: they never change what's sent. |
created_at | string (date-time) | |
list_id | string, nullable | |
timezone | string, nullable | |
custom | object | The lead's custom fields. |
campaigns | array of object | The campaigns it's in (the 50 most recent). |
LeadUnsubscribed
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
email | string | |
status | string | |
campaigns_stopped | integer |
Import
| Field | Type | Notes |
|---|---|---|
object | string | |
list_id | string | |
list_name | string | |
imported | integer | New leads. |
updated | integer | Leads already in the workspace, updated and moved into the list. |
skipped | integer | Rows without a usable address, or past the room the workspace has for new leads. |
blocked | integer | On the blocklist — not added. |
custom_fields | array of string | |
errors | array of object |
Enrollment
| Field | Type | Notes |
|---|---|---|
object | string | |
campaign_id | string | |
list_id | string | |
imported | integer | |
updated | integer | |
skipped | integer | |
blocked | integer | |
enrolled | integer | People added to the campaign now. |
in_list | integer, nullable | When enrolling a whole list: its size. |
skipped_active_elsewhere | integer | |
campaign_status | DRAFT · SENDING · PAUSED · FINISHED | |
errors | array of object |
RowError
| Field | Type | Notes |
|---|---|---|
row | integer | |
email | string | |
reason | string |
List
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
name | string | |
leads | integer | |
created_at | string (date-time) |
Conversation
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
channel | email · linkedin | email, or linkedin: a LinkedIn conversation, answered from the Replies page in MailFleet — POST /replies/{id}/reply refuses it. |
subject | string, nullable | |
class | string | How the inbox classifies it: a mark (Interested, Meeting request …), or Reply. |
intent | INTERESTED · MEETING · QUESTION · NOT_NOW · NEUTRAL · UNSUBSCRIBE | |
tags | array of string | Your own labels. |
handled | boolean | |
read | boolean | |
starred | boolean | |
snoozed_until | string (date-time), nullable | |
received_at | string (date-time) | |
sender | string, nullable | The mailbox it arrived on. |
lead | objectid email name company title phone status | |
campaign | object, nullableid name status | |
messages | array of object | |
notes | array of object | |
not_shown | string | Present when a very long history was cut: what was left out. |
Message
| Field | Type | Notes |
|---|---|---|
direction | out · in | |
kind | campaign_email · reply_received · reply_sent | |
from | string, nullable | |
to | string, nullable | reply_received: who their email was addressed to, comma-separated (your mailbox for emails recorded before 23 October 2026). |
cc | array of string | reply_sent: who your reply was copied on (Cc). reply_received: who their email was copied on (recorded from 23 October 2026). |
bcc | array of string | reply_sent: who your reply was copied on without the others seeing (Bcc). reply_received: only when the copy you received shows a Bcc, which is rare. |
files | array of object | reply_received: the files their email carried (recorded from 23 October 2026). `image` is true for a picture you can see in the Replies inbox; other files are only named — open them in the mailbox. |
subject | string, nullable | |
text | string | Without the quoted history; up to 4,000 characters. |
text_truncated | boolean | Present (true) when the text was cut. |
at | string (date-time) | |
step | integer, nullable | campaign_email: which step it was. |
campaign | string, nullable | campaign_email: the campaign's name. |
delivery | string, nullable | campaign_email: delivered, bounced or blocked. |
opened_at | string (date-time), nullable | campaign_email: first recorded open. |
clicked_at | string (date-time), nullable | campaign_email: first click by a person. |
ReplyPatch
| Field | Type | Notes |
|---|---|---|
mark | Interested · Meeting request · Question · Not now · Not interested · OOO · Wrong person · Referral · Meeting booked · Won · Unsubscribed | "Mark lead as" — the classification and what goes with it. |
handled | boolean | Resolve (or reopen) the whole conversation. |
read | boolean | |
tags | array of string | Your own labels (replaces them). |
starred | boolean | |
snoozed_until | string (date-time), nullable | Out of the inbox until then (within a year); null wakes it. |
SentMessage
| Field | Type | Notes |
|---|---|---|
object | string | |
direction | string | |
reply_id | string | |
to | string | |
cc | array of string | Who it was copied on (the mail server took them). |
bcc | array of string | |
copies_refused | array of string | Present only when the mail server turned down a cc or bcc address: the reply went, they got no copy. |
subject | string | |
sender_id | string | |
sent_at | string (date-time) |
BlocklistEntry
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
value | string | |
kind | email · domain | |
note | string, nullable | |
created_at | string (date-time) |
BlocklistResult
| Field | Type | Notes |
|---|---|---|
object | string | |
added | integer | |
already_blocked | integer | |
invalid | array of string | Entries that aren't an address or a domain. |
leads_blocked | integer | Existing leads now Blocked and stopped. |
Webhook
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
url | string | |
events | array of email.sent · email.opened · link.clicked · reply.received · reply.interested · reply.tagged · email.bounced · lead.unsubscribed · lead.enriched · deal.created · deal.stage_changed · deal.won · deal.lost | |
active | boolean | |
last_status | integer, nullable | |
last_fired_at | string (date-time), nullable | |
created_at | string (date-time) | |
secret | string | Only when it's created — keep it to verify signatures. |
Deleted
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
deleted | boolean |
LeadDbPerson
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | Lead Database person id — the handle for /leaddb/reveal. |
full_name | string | |
first_name | string, nullable | |
last_name | string, nullable | |
title | string, nullable | |
seniority | string, nullable | |
email_masked | string, nullable | Masked. Reveal the address with /leaddb/reveal. |
email_status | string, nullable | What the source data claims: verified, extrapolated or unavailable. |
email_corporate | boolean | |
email_check | string, nullable | Our verifier's own last verdict — stronger than email_status. Null = never checked. |
email_checked_at | string (date-time), nullable | |
has_phone | boolean | |
linkedin_url | string, nullable | |
city | string, nullable | |
state | string, nullable | |
country | string, nullable | |
company | objectname domain industry employees | |
acquired | boolean | You have already paid for this person — revealing them again is free. |
LeadDbPagination
| Field | Type | Notes |
|---|---|---|
total | integer | |
limit | integer | |
offset | integer | |
has_more | boolean | |
capped | boolean | total is a floor, not a count: more than count_cap people match, or the search was too broad to count in time (a category filter), so total only says at least this many. has_more still says whether there is another page. |
count_cap | integer |
LeadDbReveal
| Field | Type | Notes |
|---|---|---|
object | string | |
person_id | string | |
email | string | |
verification | objectoutcome code checked_at cached | |
charged | boolean | False when you had already paid for this person. |
lead_id | string, nullable | The lead this person is in your workspace — saved by the reveal, already there, or added by add_to_list. Null when they aren't one of your leads. |
saved_to_leads | boolean | The person is one of your leads after this call: saved by the reveal (it takes one place in your workspace), or already one. False on a workspace still on monthly lead credits unless add_to_list was used, and when the save didn't happen — see save_note. |
lead_list | object, nullableid name | The list the lead is in — "Revealed from Lead Database" unless add_to_list named another. Null when not a lead, or in no list. |
save_note | string, nullable | Why the address was handed over but the person wasn't saved to your leads (the address would bounce, it's blocklisted, the workspace filled up meanwhile, or a fault of ours), in a plain sentence. Null otherwise. |
quota | objectused cap remaining period | Your Lead Database allowance after this call. Null caps mean unlimited. |
EnrichmentPending
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string | |
lead_id | string | |
status | pending |
Enrichment
| Field | Type | Notes |
|---|---|---|
object | string | |
id | string, nullable | |
lead_id | string | |
status | pending · done · not_found · failed | |
phone | string, nullable | The person's mobile or direct line. Never the company switchboard. |
updated_at | string (date-time), nullable |
Stats
| Field | Type | Notes |
|---|---|---|
object | string | |
campaigns | objecttotal sending | |
senders | objecttotal active | |
leads | objecttotal | |
replies | objecttotal unhandled | |
emails | objectsent_all_time sent_today delivered_all_time | |
engagement | objectreplied interested bounced hard_bounced blocked leads_reached auto_replied | Added up across campaigns, counted as each campaign's stats are: people who replied (out-of-office and auto-replies left out) and were interested; emails that bounced. |
Errors
Errors are JSON with the same shape throughout: { "error": { "code": "invalid_request", "message": "Each lead needs a valid email address.", "param": "leads.3.email" } }. The message is plain words, safe to show a person; param names the field that failed.
| Status | What it means |
|---|---|
400 | The body or a parameter isn't valid — error.param names the field. A campaign that can't start yet lists what's missing in error.blockers. |
401 | Missing, invalid or revoked API key. |
403 | read_only_key: a read-only key tried to make a change. plan_required: the API is a Pro and Scale feature. |
404 | No such resource in your workspace. |
409 | It can't happen right now: a campaign that isn't sending, the same reply within a minute (duplicate_reply), a reply to a lead who unsubscribed without confirm_unsubscribed: true (unsubscribed), an address another lead uses (email_taken), or a request with the same Idempotency-Key still running. |
413 | The request body is over 5 MB. |
422 | It can't be done as asked: a reply to a lead on your blocklist (blocklisted — nothing overrides it), an Idempotency-Key already used for a different request (idempotency_key_reused), or a conversation on LinkedIn — answered from the Replies page, not through the API (linkedin_conversation). |
429 | More than 120 requests in a minute from one key. Retry-After says how many seconds to wait. |
502 | The mail server refused a reply; the message says why in plain words. |