Connection
- Authentication: API key (Instantly API key (version 2)).
In Instantly: Settings → Integrations → API Keys tab → pick “Version 2” → Create API Key. Name it and choose targeted scopes (they cannot be edited afterwards): campaigns:read and campaigns:update, leads:read, leads:create and leads:update, lead_lists:read and lead_lists:create, accounts:read, emails:read, workspaces:read. Avoid all:all. Copy the key when it is shown. API access depends on your Instantly plan: see instantly.ai/pricing.See Instantly’s documentation.
Read actions (10)
| Action | Description |
|---|---|
get_campaign | Get one campaign: status, schedule, sequences (steps and e-mail variants) and settings. id (string, UUID) comes from list_campaigns. |
get_campaign_analytics | Get sent / opened / replied / bounced counts per campaign (an array, one entry per campaign). All arguments optional: id (string, UUID of one campaign); ids (array of campaign UUID strings); both empty = all campaigns; start_date and end_date (strings, YYYY-MM-DD or ISO 8601 timestamp, UTC); exclude_total_leads_count (boolean, faster when the total is not needed). |
get_campaign_analytics_overview | Get the aggregated analytics of one, several or all campaigns (a single object: sent, opens, replies, bounces, opportunities…). All arguments optional: id (string, UUID of one campaign); ids (array of campaign UUID strings); both empty = all campaigns; start_date and end_date (strings, YYYY-MM-DD or ISO 8601 timestamp, UTC); campaign_status (number, 0 Draft, 1 Active, 2 Paused, 3 Completed, 4 Running Subsequences, -99 Account Suspended, -1 Accounts Unhealthy, -2 Bounce Protect); expand_crm_events (boolean, true = count every occurrence of the interest events instead of the first one per contact). |
get_lead | Get one lead: contact fields, campaign, list, interest status, open / click / reply counters. id (string, UUID of the lead) comes from list_leads. |
get_workspace | Get the workspace behind the API key: { id, name, owner, plan_id, … }. No arguments. |
list_accounts | List the sending e-mail accounts with status, daily limit and warmup score (the spec returns no SMTP / IMAP password): { items, next_starting_after }. All arguments optional: limit (integer 1 to 100); starting_after (string, cursor); search (string, match on the e-mail address); status (number, 1 Active, 2 Paused, 3 Temporarily paused for maintenance, -1 Connection Error, -2 Soft Bounce Error, -3 Sending Error); provider_code (number, 1 Custom IMAP/SMTP, 2 Google, 3 Microsoft, 4 AWS, 8 AirMail, 11 Airmail Instant); filter (string, one of ACC_FILTER_PAUSED, ACC_FILTER_ERROR, ACC_FILTER_NO_CTD, ACC_FILTER_PW_ACCOUNTS, ACC_FILTER_DFY, ACC_FILTER_DFY_SETUP_PENDING, ACC_FILTER_W_ACTIVE, ACC_FILTER_W_PAUSED, ACC_FILTER_W_ERROR); sort_by (string: timestamp_created, email, stat_warmup_score or status); sort_order (string: asc or desc); skip (integer >= 0); include_tags (boolean). |
list_campaigns | List campaigns with their status, sequences and settings: { items, next_starting_after }. All arguments optional: limit (integer 1 to 100); starting_after (string, cursor = next_starting_after of the previous page); search (string, match on the campaign name); status (number, 0 Draft, 1 Active, 2 Paused, 3 Completed, 4 Running Subsequences, -99 Account Suspended, -1 Accounts Unhealthy, -2 Bounce Protect); exclude_status (number, same values: hide those campaigns); tag_ids (string, comma-separated tag UUIDs). |
list_emails | List e-mails of the unified inbox (sent and received, with subject and body): { items, next_starting_after }. Rate limit 20 requests per minute. All arguments optional: limit (integer 1 to 100); starting_after (string, cursor); search (string); campaign_id and list_id (strings, UUIDs); lead (string, e-mail of the lead); eaccount (string, sending account e-mail, comma-separated for several); company_domain (string); email_type (string: received, sent or manual); mode (string: emode_focused, emode_others or emode_all); is_unread, has_reminder, scheduled_only, marked_as_done, latest_of_thread, preview_only (booleans); i_status (number, interest status of the thread); sort_order (string: asc or desc, by creation date, default desc); min_timestamp_created and max_timestamp_created (strings, ISO 8601); assigned_to (string, user UUID). |
list_lead_lists | List the lead lists: { items: [{ id, name, has_enrichment_task, … }], next_starting_after }. All arguments optional: limit (integer 1 to 100); starting_after (string, cursor = next_starting_after of the previous page); search (string, match on the list name); has_enrichment_task (boolean). |
list_leads | List or search leads (a read-only query, sent as POST by Instantly): { items, next_starting_after }. All arguments optional: campaign (string, campaign UUID); list_id (string, lead list UUID); search (string, whole words or the start of a value among e-mail, names, company, job title; give campaign or list_id to also match inside values); filter (string, one of FILTER_VAL_CONTACTED, FILTER_VAL_NOT_CONTACTED, FILTER_VAL_COMPLETED, FILTER_VAL_UNSUBSCRIBED, FILTER_VAL_ACTIVE, FILTER_LEAD_INTERESTED, FILTER_LEAD_NOT_INTERESTED, FILTER_LEAD_MEETING_BOOKED, FILTER_LEAD_MEETING_COMPLETED, FILTER_LEAD_CLOSED, FILTER_LEAD_OUT_OF_OFFICE, FILTER_LEAD_WRONG_PERSON, FILTER_LEAD_LOST, FILTER_LEAD_NO_SHOW, FILTER_LEAD_CUSTOM_LABEL_POSITIVE, FILTER_LEAD_CUSTOM_LABEL_NEGATIVE, FILTER_VAL_BOUNCED, FILTER_VAL_SKIPPED, FILTER_VAL_RISKY, FILTER_VAL_INVALID, FILTER_VAL_VALID, FILTER_VAL_CATCH_ALL, FILTER_VAL_NOT_VERIFIED, FILTER_VAL_IN_SUBSEQUENCE, FILTER_VAL_OPENED_NO_REPLY, FILTER_VAL_COMPLETED_NO_REPLY, FILTER_VAL_NO_OPENS, FILTER_VAL_REPLIED, FILTER_VAL_LINK_CLICKED); contacts (array of e-mail strings); ids (array of lead UUID strings); excluded_ids (array of lead UUID strings); in_campaign and in_list (booleans); distinct_contacts (boolean, one row per e-mail; the cursor is then an e-mail); limit (integer 1 to 100); starting_after (string, next_starting_after of the previous page). Results are ordered by lead id. |
Write actions (6)
| Action | Description |
|---|---|
activate_campaign | Activate (start) or resume a campaign: it starts SENDING e-mails to its leads from the linked sending accounts. Argument: id (string, UUID of the campaign, from list_campaigns). Reverse with pause_campaign. |
create_lead | Add a lead to a campaign or a lead list. Arguments: email (string, required here); campaign (string, campaign UUID from list_campaigns) OR list_id (string, lead list UUID from list_lead_lists); first_name, last_name, company_name, job_title, phone, website, personalization (strings); custom_variables (object of name → string, number or boolean); lt_interest_status (number, 0 Out of Office, 1 Interested, 2 Meeting Booked, 3 Meeting Completed, 4 Won, -1 Not Interested, -2 Wrong Person, -3 Lost, -4 No Show); skip_if_in_workspace, skip_if_in_campaign, skip_if_in_list (booleans, true = do not add a duplicate); verify_leads_on_import (boolean, true = verify the e-mail, may spend verification credits). If the campaign is active, the lead starts receiving e-mails. |
create_lead_list | Create a lead list. Arguments: name (string, required); has_enrichment_task (boolean, true = enrich every added lead, may spend credits; default false); owned_by (string, UUID of the owner user; default the key owner). |
pause_campaign | Pause (stop) a campaign: no more e-mails go out until activate_campaign. Argument: id (string, UUID of the campaign, from list_campaigns). |
update_lead | Update the fields of a lead (only those given change). Arguments: id (string, UUID of the lead, from list_leads); first_name, last_name, company_name, job_title, phone, website, personalization (strings); custom_variables (object of name → string, number or boolean); lt_interest_status (number, 0 Out of Office, 1 Interested, 2 Meeting Booked, 3 Meeting Completed, 4 Won, -1 Not Interested, -2 Wrong Person, -3 Lost, -4 No Show). The e-mail cannot be changed. |
update_lead_interest_status | Set the interest status of a lead, identified by its e-mail. It may stop its campaign, update opportunities and trigger automations. Arguments: lead_email (string, e-mail of the lead); interest_value (number, 0 Out of Office, 1 Interested, 2 Meeting Booked, 3 Meeting Completed, 4 Won, -1 Not Interested, -2 Wrong Person, -3 Lost, -4 No Show; null = reset to the neutral “Lead” status); optional campaign_id and list_id (strings, UUIDs, to target the lead in that campaign or list). |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: October 2026.