Smartlead MCP Server

Smartlead

Cold-email automation. Every send is anchored to a Campaign; sequences fire from attached sender (Email Account) inboxes to Leads enrolled in the campaign. All inbound replies land in one Master Inbox spanning every campaign and sender.

Resource hierarchy (top down)

• Lead List → workspace-level staging bucket of contacts (independent of any campaign)
• Campaign → Sequence (ordered email steps with delay) → Variant
• Campaign → Lead (enrolled prospect) → Message history (sent + replies, threaded)
• Campaign ↔ Email Account (many-to-many; senders attached to a campaign)
• Email Account → Warmup settings + 7-day warmup stats
• Lead Category (workspace-wide enum applied to a lead-in-campaign mapping)
• Master Inbox → reply messages from any campaign / sender, each carrying an email_lead_map_id (== campaign_lead_map_id) used by every per-message verb

A campaign's leads are scoped to that campaign — the same email address enrolled in multiple campaigns is a separate lead row each time. The global lead listing is the workspace-wide rollup, independent of any specific Lead List.

Lead Lists (the pre-campaign staging surface)

A Lead List is a workspace-level bucket of contacts that exists independently of any campaign. The canonical sourcing flow is:

1. Build / receive a list of contacts (CSV, ListKit export, manual entry).
2. Stage them in a Lead List with import_leads_to_lead_list — reusable, taggable, and detached from any campaign.
3. push_leads_to_campaign to promote staged leads into a campaign — action='copy' keeps the source intact, action='move' removes them from the source list. Source picker is mutually exclusive: list_id (whole list), lead_ids (1-10,000 explicit ids), or all_leads=true (the entire workspace pool). Target picker accepts either campaign_id (existing) or campaign_name (auto-creates the campaign if it does not exist).

Lead List attributes: id, list_name, leads_count, active_leads_count, tag_ids, timestamps. Only list_name is mutable on update — use tags via assign_tags_to_lead_lists for grouping. List filtering: paginated with limit (1-1000, default 10), offset (≥ 0), and tag_ids (filter by tag membership). The API does not expose a free-text name filter, a description / metadata field on the list itself, or a tag-listing surface for lead lists — discover tag ids in the Smartlead UI.

Imports require file_name (label only — does not need to match a real file), lead_list (array of contact objects, max 400 per call, email required per row), and optional settings flags to bypass the workspace-wide block / unsubscribe / community-bounce / duplicate checks. The response carries uploadedCount, duplicateCount, invalidCount, totalCount — duplicates are reported, not errored. Re-import is the canonical update path.

Push semantics: Smartlead's only move operation is "list → campaign" via push_leads_to_campaign with action='move'. There is no /lead-list/move-leads endpoint — list-to-list reorganisation is not exposed by the API. Tag-based grouping (assign_tags_to_lead_lists) is the workspace-level workaround.

assign_tags_to_lead_lists operates in batches: 1-10 lists per call, with tag_ids to attach and / or remove_tag_ids to detach (each 1-10 ids, at least one of the two must be non-empty).

ID formats

All ids are integers: campaign ids (e.g. 3090077), lead ids, email-account ids, sequence ids, category ids. The Master Inbox surfaces campaign_lead_map_id for each conversation — pass it as email_lead_map_id to read-status, category, and reply verbs. Single-resource fetches use /{collection}/{id}.

Operational order (do these in this sequence)

1. Stage contacts in a Lead List (upsert_lead_list then import_leads_to_lead_list). Optional but recommended — gives a reusable, taggable bucket detached from any specific campaign.
2. Create a campaign (name only is enough at this point).
3. Attach one or more sender email accounts to the campaign — a campaign cannot send without at least one attached sender.
4. Save the sequence steps (subject, email body, delay).
5. Update the campaign's settings + schedule. The schedule update is atomic: timezone, days_of_the_week, start_hour, end_hour, min_time_btw_emails, and max_new_leads_per_day must all be supplied in the same call (the upstream endpoint rejects partial schedule patches).
6. Promote leads into the campaign — either push_leads_to_campaign from a staged Lead List (recommended) or upsert_campaign_leads for a one-off direct enrollment.
7. Set the campaign status. Status verbs accept exactly START / PAUSED / STOPPED (note the past-tense state values, not PAUSE/STOP).

Campaign status semantics

• DRAFTED — newly created, never started.
• ACTIVE — sending.
• PAUSED — temporarily halted; resume with START.
• STOPPED — terminated; further sends require recreating.
• COMPLETED — all leads finished the sequence.

Sender accounts (managed inboxes)

Sender mailboxes are attached at the workspace level via the email-accounts surface, then linked to campaigns. The API does not expose an OAuth flow to connect Gmail / Outlook / SMTP credentials — that step happens in the Smartlead web UI. What the API does expose:

• Workspace-wide sender list with per-account warmup state and 7-day warmup stats.
• Save / update of an existing sender's metadata, signature, and per-account daily send limit.
• Warmup configuration update (ramp-up, daily volume, weekend toggle, reply-rate target).
• Hard delete of a sender from the workspace.
• Many-to-many attach / detach to a specific campaign, plus the campaign's currently-attached senders.

A campaign with zero attached senders cannot be set to START.

Master Inbox (unified replies across all campaigns and senders)

Every inbound reply lands in one workspace-wide Master Inbox, regardless of which campaign or sender it came from. Three read views share one filter shape:

• view=all — every reply (read + unread)
• view=unread — only unread
• view=important — only flagged

Filters: email_status (typically Replied), campaign_id (up to 5), email_account_id (up to 20 for all, up to 10 for unread/important), campaign_team_member_id, campaign_tag_id, client_id (each up to 10), category_ids_in / category_ids_not_in (each up to 10), category_assigned, reply_time_between ([start_iso, end_iso]), free-text search (max 30 chars), sort_by (REPLY_TIME_DESC default, or SENT_TIME_DESC). Pagination: offset ≥ 0, limit 1–20.

Set fetch_message_history=true only when the full thread is required — payload is roughly 10x the latest-message-only response.

Each inbox message exposes:

• lead (email, name, company)
• campaign (id + name)
• email_account (sender id + email)
• last_message (id, subject, body, received_at, sent_from, sent_to)
• email_status, category ({id, name}), is_read, is_important, tags
• campaign_lead_map_id — the value to pass as email_lead_map_id in every per-message verb

Per-message verbs

• Read status — toggle a conversation read (read_status=true) or unread (read_status=false). Replaces the deprecated mark-unread endpoint; always use the boolean read_status form.
• Lead category — assign a category_id to a (lead, campaign) mapping, or omit it / pass null to clear. Built-in ids: 1=Interested, 2=Meeting Request, 3=Not Interested, 4=Do Not Contact, 5=Information Request. Custom workspace categories use ids surfaced by the lead-categories read.
• Reply to thread — send a reply into an existing conversation. Required: campaign_id, email_stats_id (from last_message.id), email_body. Optional: to / to_first_name / to_last_name (defaults to the lead), cc, bcc, add_signature (default true), attachments ([{file_name, url, file_type, file_size}]), and scheduled_time (ISO 8601) to queue instead of sending immediately. Threading is preserved.

Inbox limits (upstream-enforced)

• limit ≤ 20 per page across all three views.
• campaign_id array ≤ 5.
• email_account_id array ≤ 20 for all, ≤ 10 for unread / important.
• All other id-array filters ≤ 10.

Reply analytics (campaign-scoped, separate from the inbox)

Per-campaign reply counts live on the analytics endpoint. Per-reply rows live on statistics with email_status=replied (paginated). Full message thread lives on message-history keyed by (campaign_id, lead_id) — pull the lead id from the campaign's lead list, not from the global lead by email. The Master Inbox is the better entry point for cross-campaign reply triage; the campaign analytics surface is for per-campaign engagement reporting.

Date filters

Campaign analytics accept start_date / end_date in YYYY-MM-DD. Both must be supplied together; the date-filtered endpoint diverges from the cumulative one. Inbox reply_time_between uses ISO 8601 datetimes (["2025-01-01T00:00:00Z","2025-01-31T23:59:59Z"]).

Sender warmup

Newly added sender accounts default to warmup-enabled. Warmup volume should ramp before campaigns send through the account at full volume. The warmup-stats endpoint returns a 7-day rolling window only.

Deliverability defaults that work

Track-open and track-click pixels degrade deliverability for cold outreach. Plain-text bodies outperform HTML for first-touch. Caps of ~30 new leads per day per sender, business-hours-only sending, and stop_lead_settings = REPLY_TO_AN_EMAIL are the conservative starting point.