Connect your AI to Ballast

Last updated

Ballast is cold email software with every feature on every plan. Connect unlimited mailboxes, send sequences at a pace your domains survive, and handle replies in one inbox, priced by the emails you send.

Everything you can do in the dashboard is also a tool for your AI, over the Model Context Protocol (MCP). Ask Claude to draft a sequence for a list, check yesterday's replies, or find the mailbox that bounces most. It works in one workspace with your role.

Server URL

https://ballast.to/api/mcp

Apps with sign-in (Claude, ChatGPT) open Ballast, you pick the workspace and allow it. Tools that take a header (Claude Code, Cursor) use an API key from Settings, API keys. Disconnect apps or revoke keys on the same page.

Claude

In Claude, open Settings, Connectors, and add a custom connector. Name it Ballast, paste the server URL, then connect: Claude opens Ballast to sign in and pick a workspace.

ChatGPT

Add a custom connector (an MCP server) with the server URL and OAuth sign-in. ChatGPT sends you to Ballast to pick the workspace.

Claude Code

claude mcp add --transport http ballast https://ballast.to/api/mcp \
  --header "Authorization: Bearer bl_..."

With every tool (the full set):

claude mcp add --transport http ballast "https://ballast.to/api/mcp?toolset=full" \
  --header "Authorization: Bearer bl_..."

Cursor and other tools

Add it to ~/.cursor/mcp.json, or the MCP config of your tool:

{
  "mcpServers": {
    "ballast": {
      "url": "https://ballast.to/api/mcp",
      "headers": {
        "Authorization": "Bearer bl_..."
      }
    }
  }
}

Cursor works best with about 40 tools across all your servers, so the core set leaves room for others. For the full set, add a header (or put ?toolset=full on the URL):

{
  "mcpServers": {
    "ballast": {
      "url": "https://ballast.to/api/mcp",
      "headers": {
        "Authorization": "Bearer bl_...",
        "x-ballast-toolset": "full"
      }
    }
  }
}

You confirm what can't be undone

Launching a campaign, sending a reply, importing and deleting take two calls. The first only returns what will happen, for example "will email 312 leads from 6 mailboxes, first sends Tue 09:00 in each lead's time zone", and a confirmation code. Your AI shows you that and runs it only after you say yes. The code works for 10 minutes and only for those exact arguments.

Core tools and the full set

Ballast has 92 tools, the same operations as the REST API. A long tool list costs your AI context and makes it pick worse, so the server URL gives the 30 core tools: enough to set up mailboxes, import leads, write and launch a campaign, read its numbers and answer replies.

For everything else (editing leads, lists and labels, webhooks, warmup, integrations, link domains, members), connect with ?toolset=full on the URL, or send the header x-ballast-toolset: full:

https://ballast.to/api/mcp?toolset=full

Sign-in, permissions and confirmations are the same in both sets.

Core tools

Workspace

  • whoamiWho am I: the user, workspace and plan behind this key or session
  • get_billingPlan, subscription status, emails and AI drafts used this period
  • get_overviewWorkspace dashboard: sends, replies, positive replies, bounces, won, mailbox health and when and where replies come from

Domains and mailboxes

  • check_domainGrade a sending domain
  • list_domainsList sending domains with their health
  • add_domainAdd a sending domain and check it
  • list_mailboxesList mailboxes
  • add_mailboxConnect a mailbox

Leads

  • import_leadsImport leads in chunksasks to confirm
  • list_leadsList leads
  • list_lead_listsLead lists with counts
  • add_suppressionsSuppress addresses or whole domains

Campaigns

  • list_campaignsList campaigns
  • create_campaignCreate a draft campaign
  • get_campaignGet a campaign with its sequence, schedule and settings
  • update_campaignRename a campaign or change its schedule, mailboxes and options
  • set_sequenceReplace the whole sequence
  • write_sequenceWrite emails with AI from the offer profile
  • add_leads_to_campaignAdd leads from lists (or by id) to a campaign
  • preview_campaignRender every step and variant for one lead
  • get_launch_checklistWhat has to be fixed before launch
  • launch_campaignLaunch or resume a campaignasks to confirm
  • pause_campaignPause a running campaign
  • get_campaign_statsDaily emails sent, replies, bounces and opens
  • get_campaign_analyticsSends, replies and bounces by campaign, mailbox and email provider, plus reply sentiment

Replies

  • get_unibox_filtersUnibox counts by label, mailbox and campaign
  • list_threadsReply threads, newest first
  • get_threadA thread with every message, the campaign emails and the lead
  • send_replyAnswer a threadasks to confirm
  • label_threadSet or clear a thread's label

Full set only

62 more tools with ?toolset=full.

  • add_leads_to_listAdd leads to a list
  • check_integrationTest a connected key again (verifier credits left, or the AI key on its model)
  • check_link_cnameCheck a link domain CNAME
  • check_link_domainCheck the link domain now
  • check_workspace_domainRe-check a sending domain now
  • create_labelCreate a label
  • create_leadAdd one lead
  • create_lead_listCreate a list
  • create_webhookAdd a webhook endpoint
  • delete_campaignDelete a campaignasks to confirm
  • delete_labelDelete a labelasks to confirm
  • delete_lead_listDelete a listasks to confirm
  • delete_leadsDelete leadsasks to confirm
  • delete_mailboxDisconnect a mailboxasks to confirm
  • delete_webhookRemove a webhook endpointasks to confirm
  • draft_offer_profile_from_websiteDraft an offer profile from a website
  • duplicate_campaignCopy a campaign's sequence, schedule and mailboxes into a new draft (no leads)
  • get_campaign_breakdownOne campaign's results by step, A/B variant, mailbox and email provider
  • get_importImport progress and counts
  • get_leadGet a lead with custom fields, lists and labels
  • get_link_domainGet the link domain
  • get_mailbox_warmupWarmup for one mailbox
  • get_offer_profileGet the offer profile
  • get_sending_ipWhere your mailboxes connect from
  • get_sending_settingsWorkspace sending and reply settings shared by every campaign
  • import_mailboxesImport SMTP/IMAP mailboxes in bulkasks to confirm
  • label_leadsApply a label to leads
  • list_campaign_lead_sendsEmails sent to one lead in a campaign
  • list_campaign_leadsLeads in a campaign with their progress
  • list_integrationsList connected integrations
  • list_labelsLabels with their triggers and lead counts
  • list_membersMembers of this workspace, and pending invites for owners and admins
  • list_suppressionsSuppressed addresses and domains
  • list_warmupWarmup for every mailbox
  • list_webhook_deliveriesRecent deliveries to an endpoint
  • list_webhooksList webhook endpoints
  • mark_thread_readMark a thread read or unread
  • mark_wonMark a lead won
  • remove_domainRemove a domain no mailbox usesasks to confirm
  • remove_leads_from_campaignTake leads out of a campaign (they stay in the workspace)asks to confirm
  • remove_leads_from_listRemove leads from a list (the leads stay)
  • remove_link_domainRemove the link domainasks to confirm
  • remove_own_proxyStop using your own proxy
  • remove_suppressionsRemove suppressionsasks to confirm
  • rename_lead_listRename a list
  • set_ai_modelsPick the models the workspace's own AI key runs
  • set_link_domainSet the link domain
  • set_own_proxyUse your own proxy
  • suppress_leadsNever email these leads again
  • test_label_promptRun the reply classifier on a sample reply
  • test_mailboxTest a connected mailbox again
  • test_own_proxyTest your own proxy without saving
  • test_webhookSend a test event now
  • unlabel_leadsRemove a label from leads
  • update_labelChange a label, its AI prompt or triggers
  • update_leadChange a lead's fields or status
  • update_mailboxChange a mailbox's limits, signature or status
  • update_mailbox_warmupTurn warmup on or off and tune it
  • update_offer_profileSave the offer profile
  • update_sending_settingsChange the workspace sending and reply settings
  • update_webhookChange a webhook's URL, events or on/off
  • verify_leadsVerify lead addresses