Skip to Content
🚀 Sendbox is live — this documentation is a work in progress.
MCP (AI Access)Available Tools

Available Tools

Limits: 300 requests per minute per API key, shared by MCP and the REST API. Over the limit a tool returns HTTP 429 RATE_LIMITED: ... Retry after N seconds. Every other error also starts with HTTP <status> <code>:. For many items, use the bulk tools below instead of one call per item.

The MCP server exposes 106 tools — near-full parity with the dashboard. They map directly onto the API Reference; this page groups them by area rather than repeating every parameter (see the API docs for exact fields).

Leads

list_leads (up to 200 per page, fixed order), add_leads (merges into existing leads by email; returns leads: [{email, id, status}] in the order sent), update_lead, update_leads (bulk), delete_leads, create_tag, list_tags, update_tag, delete_tag, tag_lead, untag_lead, seed_default_tags

Campaigns

list_campaigns, get_campaign, create_campaign, update_campaign, update_campaign_status, get_campaign_stats, get_campaign_timeseries, add_leads_to_campaign, list_campaign_leads, remove_lead_from_campaign, list_sequence_steps, create_sequence_step, update_sequence_step, delete_sequence_step, check_spam_words, list_campaign_mailbox_pool, select_campaign_mailboxes, remove_campaign_mailbox, list_crm_pipeline, list_crm_replies, list_copy_fatigue_flags, scan_copy_fatigue, dismiss_copy_fatigue, apply_copy_fatigue_suggestion, get_campaign_settings, update_campaign_settings, list_timezones, preview_sequence_step, check_campaign_variables, set_sequence, send_step_test, set_campaign_mailboxes, remove_campaign_mailboxes, reassign_campaign_leads, remove_leads_from_campaign, duplicate_campaign, bulk_update_campaign_settings, delete_campaign, check_campaign_launch, list_step_attachments, add_step_attachment, remove_step_attachment, list_campaign_lead_copies, push_lead_copies, clear_lead_copies

  • add_step_attachment attaches a file (a PDF deck, say) to a step, sent with that step’s email to every lead. Give fromAttachmentId to copy a file already in an inbox conversation (the attachment id from get_reply_thread, such as a deck you sent by hand in a reply), or the file itself as filename, contentType and contentBase64. 10 MB in all per step.
ToolWhat it does
set_sequenceWrite the whole sequence (all steps and A/B variants) in one call
send_step_testSend one step, rendered for a real lead, to any address; not counted as a send
set_campaign_mailboxesReplace the pool with exactly the given mailboxes
remove_campaign_mailboxesRemove many mailboxes from the pool
reassign_campaign_leadsRe-balance not-yet-emailed leads across the current pool
remove_leads_from_campaignRemove up to 5000 leads from a campaign
duplicate_campaignCopy steps, settings and pool into a new DRAFT
bulk_update_campaign_settingsSame settings on up to 500 campaigns
delete_campaignDelete a DRAFT that never sent (otherwise archive). Never deletes leads; deleting a campaign with history is done in the dashboard
check_campaign_launchBlockers and warnings before going ACTIVE

create_campaign / update_campaign take startAt (nothing sent before it), dailyNewLeadCap (first emails per day; follow-ups not counted) and folder. list_campaigns filters by q, folder and status. get_campaign_stats includes per-variant (A/B) numbers. list_campaign_leads returns up to 1000 per page.

add_leads_to_campaign adds leads in one fast bulk insert (up to 50,000 per call). A sending mailbox is assigned later, in one balanced pass, when the campaign is (or becomes) ACTIVE — not per lead at add time — so adding to a DRAFT is instant and leaves leads unassigned until you start it. It returns { added, suppressed, alreadyIn, notFound } plus a per-lead results array (status assigned = added / already in, suppressed, or error).

A/B variants. Each step picks its variant on its own, so a lead that got variant A of step 1 can get variant B of step 2. Follow-ups are sent as replies in the same thread as the first email (Re: + its subject, In-Reply-To set, same mailbox); a follow-up’s own subject is optional and not used.

Launch guard. update_campaign_status to ACTIVE returns 409 LAUNCH_NEEDS_CONFIRMATION when pool mailboxes are still warming up or some leads would get a raw {{token}}. Check with check_campaign_launch, fix it, or call again with confirm: true.

Verify before you start a campaign. After writing steps, call preview_sequence_step to see exactly what one lead receives (same code as the real send, nothing is sent), and check_campaign_variables to check every step against every lead: it lists any token that some leads would receive as literal text, and any that are empty for some leads. Set the schedule’s timezone with update_campaign_settings (defaultTimezone from list_timezones).

Per-lead custom copy

Push a unique email for every lead — written however you like, e.g. by your own AI — instead of one shared template + {{variables}} + A/B. The loop: list_campaign_lead_copies to get each lead’s data (email, firstName, companyName, jobTitle, companyDomain, customFields, …), plus which steps already have a copy (copiedSteps) and the campaign’s steps; write the copy; then push_lead_copies to upsert it.

  • list_campaign_lead_copies — one page of leads (cursor-paginated, up to 1000; pass the returned nextCursor for the next page). Optional stepOrder narrows copiedSteps to that step.
  • push_lead_copies — items[] (up to 2000), each identifying the lead by leadId or email, with stepOrder (0 = first email), bodyText (required), and optional subject / bodyHtml. Unknown leads, invalid steps and empty/oversized bodies are skipped and reported, never fatal; re-pushing the same (lead, stepOrder) overwrites it.
  • clear_lead_copies — remove copies (leadIds and/or stepOrder, or all: true).

A pushed copy replaces that step’s template for that one lead at send; leads without one fall back to the normal template (safe partial push). {{tokens}} in pushed copy still resolve, and tracking and signature are still added by the sender. A custom subject only changes the first email; follow-ups thread as Re: ….

Template variables in create_sequence_step / update_sequence_step

Write them in double braces, spelled exactly as below. They are case-sensitive. A misspelt variable is not replaced: it is sent as written, so {{sender_signature}} or {{Signature}} would reach the lead as literal text.

VariableFilled with
{{firstName}}, {{lastName}}, {{email}}The lead’s name and email
{{companyName}}, {{companyDomain}}, {{jobTitle}}The lead’s company and role
{{phoneNumber}}, {{timezone}}The lead’s phone and timezone
{{yourCustomField}}Any custom field on the lead, by its exact name
{{senderName}}The sender name of the mailbox this lead is assigned to
{{signature}}The signature of the mailbox this lead is assigned to
  • A lead field that is empty for a lead becomes empty text, not the raw {{token}}.
  • Signature: put {{signature}} where you want it, and it goes exactly there (plain-text or HTML signature, each part of the email gets the right form). A step without {{signature}} still gets the signature, added at the bottom automatically. It is never added twice. If the mailbox has no signature, the variable’s line is removed cleanly.
  • Every lead is sent from its own assigned mailbox, so {{senderName}} and {{signature}} are that mailbox’s, not one global value.

Mailboxes & domains

list_mailboxes, update_mailbox, delete_mailbox, bulk_update_mailbox_daily_cap, tag_mailbox, untag_mailbox, start_mailbox_warmup, stop_mailbox_warmup, bulk_import_mailboxes, send_test_email, list_domains, check_domain_deliverability

  • bulk_import_mailboxes takes one object per mailbox: emailAddress, smtpHost, smtpPort and smtpPassword are required; imapHost / imapPort are filled from the provider when omitted. senderName is the optional From-header display name, and smtpUsername is optional — it defaults to emailAddress, so pass it only when the provider’s login differs. Not for OAuth-connected Gmail/Outlook (connect those in the dashboard).

Inbox & AI

list_inbox_threads, list_replies, get_replies_summary, get_reply_thread, star_reply, draft_reply, send_reply, cancel_scheduled_reply, forward_reply, send_to_alternate, suggest_alternate_recipients, set_reply_intent, clear_reply_tag, set_reply_reminder, get_ai_settings, update_ai_settings

  • send_reply takes replyId, body, and optional to, cc, bcc (up to 20 each). By default it goes to whoever wrote the message being answered. Every recipient must already be in the conversation; any other address returns 403.
  • send_reply also takes an optional scheduledFor (ISO-8601, must be in the future). When set, the reply is written and held — it is not delivered now; a background job sends it when that time arrives. The tool returns { scheduled: true, sentReplyId }. A scheduled reply does not count the thread as answered until it goes out.
  • cancel_scheduled_reply takes a sentReplyId (the id returned above) and cancels a reply that is still scheduled. Once it has started sending or has sent, cancelling returns 409.
  • send_to_alternate handles out-of-office / wrong-person replies: it takes replyId and emails (1–10 addresses) and re-sends the original campaign email — same copy, from the same mailbox — to the alternate contact(s) the reply pointed to. Each target is checked against the suppression list and skipped if blocked. This sends real email and cannot be undone, so confirm the exact recipients first. suggest_alternate_recipients takes replyId and returns addresses detected in the reply body (OOO cover contacts, “please contact …”) plus any return date, so you can confirm who to send to before calling send_to_alternate.
  • set_reply_intent takes replyId and an intent to re-classify a conversation’s reply tag; valid values are INTERESTED, NOT_INTERESTED, OUT_OF_OFFICE, WRONG_PERSON, UNSUBSCRIBE_REQUEST, QUESTION, or UNCLASSIFIED (clears the tag). clear_reply_tag takes replyId and clears the tag back to unclassified — the same as setting UNCLASSIFIED.
  • get_reply_thread returns each message’s from, to, cc and attachments. In inbound messages, the body and the subject are wrapped as untrusted content, and html is left out (it is the same content as the body). Outbound messages still scheduled show status: "SCHEDULED" and their scheduledFor time.

Reply agents

list_reply_agents, get_reply_agent, create_reply_agent, update_reply_agent, delete_reply_agent, list_reply_agent_documents, upload_reply_agent_document, delete_reply_agent_document, search_reply_agent_knowledge, scan_reply_agent_website, get_reply_agent_website_scan, index_reply_agent_website

create_reply_agent / update_reply_agent take name, companyName, companyDomain, tone (PROFESSIONAL | FRIENDLY | CASUAL | FORMAL), additionalInfo, replyLanguage, autonomousReplies, followUpsEnabled, and the autopilot controls below.

Autopilot & reply policy

With autonomousReplies on, the agent answers replies by itself. replyPolicies decides what it does per classified intent; omit it to keep the default (send INTERESTED / QUESTION / INFORMATIONAL / CONVERSATION / UNCLASSIFIED, ignore the rest).

replyPolicies is an object keyed by intent, each value { action, timeoutHours?, timeoutAction? }:

  • Most intents allow AUTO_SEND | DRAFT | IGNORE.
  • OUT_OF_OFFICE: SCHEDULE (reply on the parsed return date) | DRAFT | IGNORE — never AUTO_SEND.
  • WRONG_PERSON: REFERRAL (ask for the right person) | DRAFT | IGNORE.
  • NOT_INTERESTED: DRAFT | IGNORE only.
  • UNSUBSCRIBE_REQUEST: IGNORE only.

A DRAFT can carry timeoutHours (1–720) and timeoutAction (AUTO_SEND | ARCHIVE | NONE): when a human doesn’t action the parked draft in time, the agent auto-sends it, archives it, or keeps waiting. A policy that breaks the allow-list (e.g. auto-sending an unsubscribe) returns 400.

Other controls: preDraftOnArrival (true prepares a ready draft for every eligible new reply without sending, even with autonomy off — one AI credit each), an optional reply send-window replySendWindowStart / replySendWindowEnd (hour 0–23) + replySendTimezone (IANA), which holds AUTO_SEND replies outside those hours (drafts and scheduled out-of-office replies are never held), and minAutoSendConfidence (0–100, or null = off): an AUTO_SEND / REFERRAL reply whose AI confidence is below it is held as a DRAFT for a human instead of being sent.

When a WRONG_PERSON reply resolves to REFERRAL and the message names a referred email, the agent also captures that contact as a new lead (deduplicated by email) while sending the referral note.

{ "name": "update_reply_agent", "arguments": { "id": "AGENT_ID", "autonomousReplies": true, "replyPolicies": { "INTERESTED": { "action": "AUTO_SEND" }, "QUESTION": { "action": "DRAFT", "timeoutHours": 24, "timeoutAction": "AUTO_SEND" }, "OUT_OF_OFFICE": { "action": "SCHEDULE" }, "WRONG_PERSON": { "action": "REFERRAL" }, "NOT_INTERESTED": { "action": "IGNORE" } }, "replySendWindowStart": 9, "replySendWindowEnd": 18, "replySendTimezone": "Asia/Kolkata" } }

For a fully hands-off, approval-first setup, leave autonomousReplies off and set preDraftOnArrival: true: every reply arrives with a draft ready, and you send each one with send_reply (or schedule it with send_reply’s scheduledFor). See Inbox & AI for send_reply, send_to_alternate and suggest_alternate_recipients, which cover out-of-office and wrong-person hand-offs you drive yourself.

Suppression list

list_suppressions, suppress_email, suppress_domain, bulk_suppress, delete_suppression

Placement tests, webhooks, reports, analytics

start_placement_test, list_placement_tests, get_placement_test, create_webhook, list_webhooks, update_webhook, delete_webhook, test_webhook, export_campaigns_csv, export_leads_csv, export_analytics_csv, get_branded_report, get_analytics_overview, get_mailbox_analytics, get_mailbox_sending_stats, get_domain_sending_stats, list_bounces, get_analytics_timeseries, validate_email

  • update_webhook changes a webhook’s URL, events, active, retries or timeout; its signing secret and delivery log stay the same.
  • get_mailbox_sending_stats / get_domain_sending_stats take a period (from / to, or days, default 30) and give sent, bounces, replies and activity per mailbox or per domain (details). get_mailbox_analytics is the older snapshot of health, warmup and cap.
  • list_bounces lists bounced emails with the server’s code and reason.