The Instantly API is the REST interface to Instantly, the cold email platform. Version 2 lives at api.instantly.ai/api/v2, authenticates with Bearer keys that carry scopes, and covers almost everything the app does: campaigns, leads, email accounts and warmup, the Unibox, analytics, webhooks, SuperSearch enrichment and Instantly's AI agents. API access comes with the paid outreach plans, from Growth at $47 a month according to Instantly's help center, webhooks start on Hypergrowth at $97, and the whole workspace shares a limit of 100 requests a second and 6,000 a minute. Instantly also runs an official hosted MCP server at mcp.instantly.ai.
It is a strong API for automating your own Instantly workspace, and it is not licensed or built to sit under a product you sell to others. Instantly's terms limit use to your own B2B outreach and forbid reselling the platform or building a competing product, its webhooks are unsigned, and campaign steps can only be emails. We read Instantly's developer docs and its public OpenAPI file, in which we counted 185 paths and 255 operations, its help center, pricing page and terms of 22 September 2026, and we connected its hosted MCP server to a workspace to see what it exposes.
What does the Instantly API cover?
Nearly the whole product. The v2 spec groups its 255 operations into 36 families, and the ones a developer touches first behave like this:
| Area | Main endpoints | What to know |
|---|---|---|
| Campaigns | POST /campaigns, then POST /campaigns/{id}/activate or /pause | The sequences field is an array, but only its first element is used, and every step must be an email |
| Leads | POST /leads for one, POST /leads/add for up to 1,000 | The bulk call takes a campaign_id or a list_id, never both. Listing leads is a POST, so filters fit in the body |
| Email accounts | POST /accounts, PATCH /accounts/{email} | Accounts are keyed by email address. daily_limit, sending_gap and the warmup settings live here |
| Warmup | POST /accounts/warmup/enable and /disable | Up to 100 listed accounts per call, or every account at once, processed as a background job you poll |
| Unibox | GET /emails, POST /emails/reply | You can only reply to an existing email, and listing emails is capped at 20 requests a minute |
| Analytics | GET /campaigns/analytics, /overview, /daily, /steps | Leave the campaign id empty to get every campaign at once |
| Webhooks | POST /webhooks, POST /webhooks/{id}/resume | Hypergrowth and above, unsigned, switched off after repeated failures |
| Enrichment | /supersearch-enrichment/* | Uses Instantly Credits, a separate subscription |
| AI agents | /ai-agents/sales, /inbox-manager, /deliverability | Instantly's own agents, configured over the API |
List endpoints page with a limit of up to 100 and a starting_after cursor, and long operations such as moving leads return a background job to poll on GET /background-jobs/{id}. Creating a campaign never sends anything: a new campaign is a draft until the activate call.
How do you get an Instantly API key and make a first call?
In the app, under Settings, Integrations, API Keys, you create a v2 key and pick its scopes. Instantly shows the key once and cannot show it again. Scopes follow a resource:action pattern, such as leads:create or campaigns:read, with all as a wildcard on either side, and a call without the right scope gets a 403. A workspace can hold several keys, each revocable, so a reporting job and an agent that adds leads can run on different keys with different rights.
A key belongs to one workspace. An agency with several client workspaces can group them and use one admin key with an x-as-workspace header, but each workspace still needs its own subscription. Keys from API v1 do not work on v2. Instantly's migration guide says v1 was deprecated on 19 January 2026, while the introduction of its API reference still says it plans to deprecate v1 in 2025, so build only on v2, even though Instantly says existing v1 integrations such as Zapier keep working.
A first call that adds a lead to a campaign looks like this, trimmed from the sample in Instantly's API reference:
curl --request POST \
--url https://api.instantly.ai/api/v2/leads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"campaign": "01a11c5e-b74f-744d-b8f8-c468a410a152",
"email": "example@example.com",
"first_name": "John",
"last_name": "Doe",
"company_name": "Example Inc.",
"skip_if_in_workspace": true,
"custom_variables": {
"past_customer": true
}
}
'When you pass a campaign, the email field is required, and the skip_if flags stop the same person from entering twice. Copy the docs samples with care: the rendered sample for the bulk endpoint sends both campaign_id and list_id, which that same endpoint says it does not accept.
What are the Instantly API rate limits?
100 requests a second and 6,000 a minute, counted per workspace rather than per key, and shared with API v1. Instantly's rate limit page says requests are blocked when either limit is reached, with a 429 response. Adding keys adds no capacity, so a reporting job, an agent and an import script on the same workspace draw from one budget.
Several endpoints are much tighter than the global limit:
| Endpoint | Documented limit |
|---|---|
| GET /emails, listing Unibox emails | 20 requests a minute |
| POST /emails/test | 10 requests a minute per workspace |
| POST /oauth/google/init and /microsoft/init | 75 a minute per workspace, 150 a minute per IP |
| POST /lead-labels/ai-reply-label | 500 requests per 30 days per workspace |
The 20-a-minute cap on listing emails matters most for anything that syncs replies by polling, which is why webhooks are the better route for replies when your plan has them. For jobs that make one call per lead, Instantly suggests batches of 100 with a two-second pause between batches, and for imports, POST /leads/add takes up to 1,000 leads per call. A Retry-After header is documented only on the OAuth endpoints, so build your own backoff for every other 429. And the terms add a softer limit on top: API calls must stay at a reasonable volume, a phrase Instantly does not define.
How do Instantly webhooks work?
You register a URL with POST /webhooks, optionally for one campaign and one event type, and Instantly posts JSON to it when the event happens. Webhooks need Hypergrowth or a higher plan. The events cover sends, opens, clicks, replies, auto-replies, bounces, unsubscribes, account errors, completed campaigns and every lead status from interested to meeting booked and wrong person, and any custom label in your workspace arrives as its own event type.
Instantly's webhook guide documents the payload as a list of fields rather than a captured example. For a reply, the fields are these, with placeholder values:
{
"timestamp": "string",
"event_type": "reply_received",
"workspace": "string",
"campaign_id": "string",
"campaign_name": "string",
"lead_email": "string",
"email_account": "string",
"unibox_url": "string",
"step": 1,
"variant": 1,
"email_id": "string",
"reply_subject": "string",
"reply_text": "string",
"reply_html": "string"
}The email_id is the value to pass as reply_to_uuid when you answer through POST /emails/reply. Lead fields from your own data can appear as extra keys.
Three behaviours are worth designing around. The deliveries are not signed: Instantly's own starter kit says there is no HMAC signature, and the only protection is a custom header you set when you create the webhook and check yourself, so put a long secret there. The names drift between subscription and payload, so you subscribe to email_link_clicked and receive link_clicked. And a webhook that keeps failing is switched off: its status goes to -1, deliveries stop, and it stays off until you resume it, over the API with POST /webhooks/{id}/resume. Instantly does not publish its retry schedule or an idempotency key, so deduplicate on your side, and watch deliveries through GET /webhook-events, while the in-app activity view shows the last three days.
Which Instantly plan do you need for the API?
A paid outreach plan, and Hypergrowth if you need webhooks. Monthly prices from Instantly's pricing page in October 2026:
| Plan | Price | Emails a month | Uploaded contacts | API | Webhooks |
|---|---|---|---|---|---|
| Growth | $47 | 5,000 | 1,000 | Yes, per the help center and pricing.md | No |
| Hypergrowth | $97 | 125,000 | 25,000 | Yes | Yes |
| Light Speed | $358 | 500,000 | 100,000 | Yes | Yes |
| Enterprise | Custom | 500,000 and more | 100,000 and more | Yes | Yes |
Growth's API access depends on the page you read. Instantly's help center and its machine-readable pricing page say every outreach plan includes the API, while the feature comparison table on the pricing page leaves "API, webhooks, and integrations" unticked for Growth and, in the same table, gives Hypergrowth 100,000 emails instead of 125,000. Almost every operation can also return 402 when the workspace has no active paid plan, and the free trial has no API access according to the help center's plan table. Growth also limits the Unibox to preview and leaves out subsequences, which matters if your integration replies to leads or branches them.
Three details change the budget. There is no overage: past a plan's included volume, you move up a tier or, from Hypergrowth, add an $87 add-on. The contacts limit is a total across campaigns, not a monthly allowance. And "unlimited email accounts" has a fair-use cap on SMTP accounts in the standard warmup pool: 100 on Growth, 500 on Hypergrowth and 1,000 on Light Speed. Go over it and Instantly moves every account in the workspace, Google and Outlook ones included, to the basic pool. Instantly's terms also say it currently allows at most 100 connected accounts per workspace, which sits oddly with the unlimited claim. Enrichment, verification and the AI agents run on Instantly Credits, a separate subscription from $9 a month.
What is the Instantly MCP server?
It is Instantly's hosted Model Context Protocol server, at mcp.instantly.ai/mcp, which lets an AI assistant such as Claude, Cursor or an n8n agent call the Instantly API as tools. It is free with an Instantly subscription and authenticates with the same API key. Instantly's authentication page recommends sending the key in a header and warns that the alternative, putting the key in the URL, may get it recorded in server logs. Its own quickstart for Claude Desktop and Cursor uses the URL form anyway, so prefer the header wherever your client supports it.
How many tools it exposes depends on which Instantly page you read: 31 in the help center, about 200 in the README of its Grok plugin, 156 in the local MCP mode of its command-line tool, and every API endpoint according to the developer docs, which would be 255. When we connected the hosted server to a workspace and asked it to describe itself, it reported the name instantly-mcp, version 2.0.0, and 199 tools across 36 categories, led by accounts, campaigns, leads and Lead Finder agents with 13 tools each. We found no tools for API keys, OAuth or Instantly's AI Sales Agent, which the docs list.
Before you hand that server to an agent, read the tool descriptions. delete_campaign says the action cannot be undone. The tool that orders domains and mailboxes says it spends real money and requires an explicit confirmation parameter. The bulk lead delete tool has no confirmation parameter at all. Since the server can only do what its key allows, the safest setup is a dedicated key with read scopes, plus only the write scopes the agent's job needs.
Can you build a product on the Instantly API?
For your own outreach, yes. To sell outreach to your own users, not under Instantly's terms. The terms define the permitted purpose as the subscriber's own direct B2B sales, marketing, recruiting and business development. They forbid sublicensing, reselling or otherwise letting unauthorized third parties use the platform, building a similar or competitive product, and using data from the service to build a product intended for third-party access. There is no separate API agreement: the API falls under the same terms.
Agencies have one sanctioned route. The white-label agency portal, on Hypergrowth and Light Speed, lets clients log in to a branded portal on your domain, one portal per workspace, and clients with campaign access see every campaign in that workspace. To keep clients from seeing each other's campaigns, Instantly recommends separate workspaces, each with its own subscription. A software company that wants outreach inside its own product, for its own customers, is outside what Instantly allows, and it would also hit the email-only steps and the shared workspace rate limit. Our guide to Instantly alternatives compares the platforms you can switch to, and our outreach API comparison covers the APIs built to sit under a product.
How does the Instantly API compare with the Swarmhit Smart API?
They answer different questions. The Instantly API automates an Instantly workspace you use for your own sending. The Swarmhit Smart API is outreach infrastructure built to sit under your own product or AI agent, and as far as we know, Swarmhit is the only Smart API provider: the engine runs behind the API, so one call creates a campaign with its whole sequence, and Swarmhit handles pacing, rotation across mailboxes and senders, caps and reply detection.
| Instantly API | Swarmhit Smart API | |
|---|---|---|
| Built for | Automating your own Instantly workspace | Putting outreach inside your product or agent |
| Channels | Email steps only | LinkedIn steps, and email steps in beta, in one sequence |
| Limits | 100 requests a second and 6,000 a minute per workspace | Per-sender limits enforced on the server, with a 429 that says which cap, how much is used and when it resets |
| Webhooks | Hypergrowth and above, unsigned | Signed with HMAC-SHA256 |
| Pricing | Plans by emails and contacts, from $47 a month | Cold email from $59 a month for 50,000 sends with unlimited mailboxes, in beta. LinkedIn from $16.90 per sender a month |
Cold email on Swarmhit is in beta, opened workspace by workspace, and its pricing may change during the beta. You pay for the emails you send, not for mailboxes or contacts, and you can connect your own Google, Microsoft or IMAP mailboxes or buy a domain and mailboxes that arrive connected and warming. The Swarmhit cold email API page has the details. If you are still choosing how to send, our guides to the email API landscape, Gmail sending limits and Outlook sending limits cover the mailbox side, and our comparison of cold email software covers the tools.
Build outreach into your own product
The Swarmhit Smart API runs LinkedIn and email steps in one campaign, with per-sender limits enforced on the server and signed webhooks for every reply.
Cold email in beta from $59 a month for 50,000 sends; LinkedIn from $16.90 per sender a month, tiered down to $6.90.
FAQ
Does Instantly have an API?
Yes. Instantly's API v2 is a REST API at api.instantly.ai/api/v2 with Bearer authentication and scoped keys. Its public OpenAPI file lists 255 operations across campaigns, leads, email accounts, warmup, the Unibox, analytics, webhooks, enrichment and AI agents. API v1 was deprecated on 19 January 2026 and its keys do not work on v2. Instantly also publishes an official TypeScript SDK in beta and a hosted MCP server.
Is the Instantly API free?
It costs nothing on top of a paid outreach plan, with no per-call fee, but it is not available for free. The help center says API access comes with every paid outreach plan from Growth at $47 a month, although the pricing page's comparison table suggests Hypergrowth. The free trial has no API access, webhooks need Hypergrowth at $97, and enrichment calls use Instantly Credits, a separate subscription.
Where do I find my Instantly API key?
In the Instantly app, under Settings, Integrations, API Keys. Create a v2 key, choose its scopes, and copy it right away, because Instantly shows it only once. You can create several keys with different scopes and revoke any of them. Each key belongs to one workspace, keys made for API v1 do not work on v2, and a call missing the required scope returns a 403 error.
What is the Instantly API rate limit?
100 requests a second and 6,000 requests a minute for the whole workspace, shared by all its API keys and by API v1. Going over returns a 429. Some endpoints are stricter: listing Unibox emails allows 20 requests a minute, sending a test email 10 a minute, and starting a Google or Microsoft OAuth connection 75 a minute per workspace. Instantly suggests grouping calls in batches of 100 with a two-second pause.
Does Instantly have an MCP server?
Yes. Instantly hosts an official MCP server at mcp.instantly.ai/mcp, free with a subscription, which lets AI assistants such as Claude or Cursor call the Instantly API as tools using your API key. Send the key in a header rather than in the URL, which Instantly warns can end up in logs. When we connected it, the server reported 199 tools across 36 categories, more than the 31 its help center lists.
Can I build a SaaS product on the Instantly API?
Not one that sells outreach to your own users. Instantly's terms limit use to the subscriber's own B2B outreach and forbid reselling or sublicensing the platform, building a competitive product, and using its data in a product meant for third parties. Agencies can serve clients through Instantly's white-label portal, with a separate workspace and subscription for each client whose campaigns must stay private. Products that need outreach for their users should use an API built for that.
