The full Instantly REST API v2 — 129 paths, 173 operations across 28 resource groups, published as OpenAPI 3.1.0 by Instantly at api.instantly.ai/openapi/api_v2.json. Every operation carries a unique operationId, a summary and documented 401/402/404/429 responses.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/instantly-ai-api-v2"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.1.0
info:
title: API Explorer
description: The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint
you will see a box with an example request. You can click on the "Try it" button to send a request to the server right
from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text.
version: 2.0.0
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
schemas:
Account:
title: Account
description: An email account that can be used to send campaigns
x-tags:
- Schemas
- Account
type: object
properties:
email:
type: string
description: Email address of the account
format: email
example: user@example.com
timestamp_created:
type: string
description: Timestamp when the account was created
readOnly: true
format: date-time
example: '2026-08-13T11:11:58.093Z'
timestamp_updated:
type: string
description: Timestamp when the account was last updated
readOnly: true
format: date-time
example: '2026-08-13T11:11:58.093Z'
first_name:
type: string
description: First name associated with the account
example: John
last_name:
type: string
description: Last name associated with the account
example: Doe
warmup:
type: object
description: Warmup configuration for the account
properties:
limit:
type: number
description: Email sending limit for the account
example: 100
advanced:
type: object
description: Advanced settings for the account
properties:
warm_ctd:
type: boolean
description: Whether the account is in warm CTD mode
example: false
open_rate:
type: number
description: Email open rate for the account
example: 0.95
important_rate:
type: number
description: Important email rate for the account
example: 0.8
read_emulation:
type: boolean
description: Whether read emulation is enabled
example: true
spam_save_rate:
type: number
description: Spam save rate for the account
example: 0.02
weekday_only:
type: boolean
description: Whether to send emails only on weekdays
example: true
warmup_custom_ftag:
type: string
description: Custom tag for the account
example: warmup
increment:
type: string
enum:
- disabled
- '0'
- '1'
- '2'
- '3'
- '4'
x-enumDescriptions:
'0': '0'
'1': '1'
'2': '2'
'3': '3'
'4': '4'
disabled: Disabled
description: Daily increment added to the sending limit, starting from 0, until the full daily limit is reached
(slow ramp). Gradually increases sending volume to improve deliverability. Set to `disabled` to send at the
full daily limit from day one.
example: disabled
reply_rate:
type: number
description: Reply rate for the account
example: 0.1
added_by:
type:
- 'null'
- string
description: User ID who added the account
readOnly: true
format: uuid
example: 019ffad2-5c8d-7f3d-bee3-56986ea16c41
daily_limit:
type:
- 'null'
- number
description: Daily email sending limit
example: 100
daily_limit_max:
type:
- 'null'
- number
description: Maximum daily email sending limit for AirMail accounts
readOnly: true
example: 100
warmup_limit_max:
type:
- 'null'
- number
description: Maximum daily warmup sending limit for AirMail accounts
readOnly: true
example: 100
modified_by:
type:
- 'null'
- string
description: User ID who last modified the account
readOnly: true
format: uuid
example: 019ffad2-5c8d-7f3d-bee3-56990262e845
tracking_domain_name:
type:
- 'null'
- string
description: Tracking domain
example: example.com
tracking_domain_status:
type:
- 'null'
- string
description: Tracking domain status
example: active
status:
type: number
description: Current status of the account
readOnly: true
enum:
- 1
- 2
- 3
- -1
- -2
- -3
x-enumDescriptions:
'1': Active
'2': Paused
'3': Temporarily paused for maintenance; will be automatically resumed shortly
'-1': Connection Error
'-2': Soft Bounce Error
'-3': Sending Error
example: 1
enable_slow_ramp:
type:
- 'null'
- boolean
description: Whether to enable slow ramp up for sending limits
example: false
inbox_placement_test_limit:
type:
- 'null'
- number
description: The limit for inbox placement tests
minimum: 0
example: 10
organization:
type: string
description: Organization ID that owns this account
readOnly: true
format: uuid
example: 019ffad2-5c8d-7f3d-bee3-569acb8bcc4f
warmup_status:
type: number
description: Current warmup status of the account
readOnly: true
enum:
- 0
- 1
- -1
- -2
- -3
x-enumDescriptions:
'0': Paused
'1': Active
'-1': Banned
'-2': Spam Folder Unknown
'-3': Permanent Suspension
example: 1
status_message:
type: object
description: Status message for the account
readOnly: true
properties:
code:
type: string
example: EENVELOPE
command:
type: string
example: DATA
response:
type: string
example: 550-5.4.5 Daily user sending limit exceeded. For more information on Gmai
e_message:
type: string
example: 'error: data command failed: 550-5.4.5 daily user sending limit exceeded'
responseCode:
type: number
example: 550
additionalProperties: true
timestamp_warmup_start:
type:
- 'null'
- string
description: Timestamp when warmup was started
readOnly: true
format: date-time
example: '2026-08-13T11:11:58.093Z'
provider_code:
type: number
description: Provider code for the account. Please make sure to specify the right provider code, otherwise your
account will not work.
enum:
- 1
- 2
- 3
- 4
- 8
- 11
x-enumDescriptions:
'1': Custom IMAP/SMTP
'2': Google
'3': Microsoft
'4': AWS
'8': AirMail
'11': Airmail Instant
example: 2
setup_pending:
type: boolean
description: Whether account setup is pending
readOnly: true
example: false
is_managed_account:
type: boolean
description: Whether this is a managed account
readOnly: true
example: false
stat_warmup_score:
type:
- 'null'
- number
description: Warmup score for the account
readOnly: true
example: 85
sending_gap:
type: number
description: The gap between emails sent from this account in minutes (minimum wait time when used with multiple
campaigns)
minimum: 0
maximum: 1440
example: 10
signature:
type:
- 'null'
- string
description: Email signature for the account
example: Best regards, John Doe
reply_to:
type:
- 'null'
- string
description: Custom reply-to email address for the account
format: email
example: reply@example.com
autofix_failed:
type:
- 'null'
- boolean
description: Whether automatic reconnection attempts have failed. null = in progress, true = failed, false = succeeded.
readOnly: true
example: false
required:
- email
- timestamp_created
- timestamp_updated
- first_name
- last_name
- organization
- warmup_status
- provider_code
- setup_pending
- is_managed_account
additionalProperties: false
Campaign:
title: Campaign
description: A campaign that can be sent to a list of recipients
x-tags:
- Schemas
- Campaign
type: object
properties:
id:
type: string
description: Unique identifier for the campaign
readOnly: true
format: uuid
example: 019ffad2-5c4b-761a-9bc4-0599e8a95bea
name:
type: string
description: Name of the campaign
example: My First Campaign
pl_value:
type:
- 'null'
- number
description: Value of every positive lead
example: 100
status:
type: number
description: Campaign Status
readOnly: true
enum:
- -99
- -1
- -2
- 0
- 1
- 2
- 3
- 4
x-enumDescriptions:
'0': Draft
'1': Active
'2': Paused
'3': Completed
'4': Running Subsequences
'-99': Account Suspended
'-1': Accounts Unhealthy
'-2': Bounce Protect
example: 1
is_evergreen:
type:
- 'null'
- boolean
description: Whether the campaign is evergreen
example: false
campaign_schedule:
type: object
description: Campaign schedule
properties:
start_date:
type:
- 'null'
- string
format: date
description: Start date in YYYY-MM-DD format. Uses the campaign's timezone.
example: '2025-09-25'
end_date:
type:
- 'null'
- string
format: date
description: End date in YYYY-MM-DD format. Uses the campaign's timezone.
example: '2025-09-25'
schedules:
type: array
items:
type: object
properties:
name:
type: string
example: My Schedule
timing:
type: object
properties:
from:
type: string
pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$
example: 09:00
to:
type: string
pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$
example: '17:00'
required:
- from
- to
days:
type: object
minProperties: 1
properties:
'0':
type: boolean
example: true
'1':
type: boolean
example: true
'2':
type: boolean
example: true
'3':
type: boolean
example: true
'4':
type: boolean
example: true
'5':
type: boolean
example: false
'6':
type: boolean
example: false
timezone:
type: string
enum:
- Etc/GMT+12
- Etc/GMT+11
- Etc/GMT+10
- America/Anchorage
- America/Dawson
- America/Creston
- America/Chihuahua
- America/Boise
- America/Belize
- America/Chicago
- America/Bahia_Banderas
- America/Regina
- America/Bogota
- America/Detroit
- America/Indiana/Marengo
- America/Caracas
- America/Asuncion
- America/Glace_Bay
- America/Campo_Grande
- America/Anguilla
- America/Santiago
- America/St_Johns
- America/Sao_Paulo
- America/Argentina/La_Rioja
- America/Araguaina
- America/Godthab
- America/Montevideo
- America/Bahia
- America/Noronha
- America/Scoresbysund
- Atlantic/Cape_Verde
- Africa/Casablanca
- America/Danmarkshavn
- Europe/Isle_of_Man
- Atlantic/Canary
- Africa/Abidjan
- Arctic/Longyearbyen
- Europe/Belgrade
- Africa/Ceuta
- Europe/Sarajevo
- Africa/Algiers
- Africa/Windhoek
- Asia/Nicosia
- Asia/Beirut
- Africa/Cairo
- Asia/Damascus
- Europe/Bucharest
- Africa/Blantyre
- Europe/Helsinki
- Europe/Istanbul
- Asia/Jerusalem
- Africa/Tripoli
- Asia/Amman
- Asia/Baghdad
- Europe/Kaliningrad
- Asia/Aden
- Africa/Addis_Ababa
- Europe/Kirov
- Europe/Astrakhan
- Asia/Tehran
- Asia/Dubai
- Asia/Baku
- Indian/Mahe
- Asia/Tbilisi
- Asia/Yerevan
- Asia/Kabul
- Antarctica/Mawson
- Asia/Yekaterinburg
- Asia/Karachi
- Asia/Kolkata
- Asia/Colombo
- Asia/Kathmandu
- Antarctica/Vostok
- Asia/Dhaka
- Asia/Rangoon
- Antarctica/Davis
- Asia/Novokuznetsk
- Asia/Hong_Kong
- Asia/Krasnoyarsk
- Asia/Brunei
- Australia/Perth
- Asia/Taipei
- Asia/Choibalsan
- Asia/Irkutsk
- Asia/Dili
- Asia/Pyongyang
- Australia/Adelaide
- Australia/Darwin
- Australia/Brisbane
- Australia/Melbourne
- Antarctica/DumontDUrville
- Australia/Currie
- Asia/Chita
- Antarctica/Macquarie
- Asia/Sakhalin
- Pacific/Auckland
- Etc/GMT-12
- Pacific/Fiji
- Asia/Anadyr
- Asia/Kamchatka
- Etc/GMT-13
- Pacific/Apia
example: Etc/GMT+12
required:
- name
- timing
- days
- timezone
minItems: 1
required:
- schedules
sequences:
type: array
description: List of sequences (the actual email copy). Even though this field is an array, only the first element
is used, so please provide only one array item, and add the steps to that array
items:
type: object
properties:
steps:
type: array
items:
type: object
properties:
type:
type: string
enum:
- email
x-enumDescriptions:
email: This steps represents an email
description: Type of step. This has to be 'email' always - it's the only supported type for now
example: email
delay:
type: number
description: The delay value before sending the NEXT email. The unit is determined by the delay_unit
field (defaults to days).
example: 2
delay_unit:
type: string
enum:
- minutes
- hours
- days
default: days
description: The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward
compatibility.
example: days
pre_delay:
type: number
description: The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences**
- this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field
(defaults to days).
example: 2
pre_delay_unit:
type: string
enum:
- minutes
- hours
- days
default: days
description: The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to
subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.
example: days
variants:
type: array
items:
type: object
properties:
subject:
type: string
example: Hello {{firstName}}
body:
type: string
description: Email body HTML. Use `<br/>` tags for delivered email line breaks.
example: Hey {{firstName}},<br/><br/>I hope you are doing well.
v_disabled:
type: boolean
description: Whether this variant is disabled. By default, all the variants are enabled. Please
set this to true if you want to disable this variant
example: true
required:
- subject
- body
required:
- type
- delay
- variants
required:
- steps
timestamp_created:
type: string
description: Timestamp when the campaign was created
readOnly: true
example: '2026-08-13T11:11:58.027Z'
timestamp_updated:
type: string
description: Timestamp when the campaign was last updated
readOnly: true
example: '2026-08-13T11:11:58.027Z'
email_gap:
type:
- 'null'
- number
description: The gap between emails in minutes
example: 10
random_wait_max:
type:
- 'null'
- number
description: The maximum random wait time in minutes
example: 10
text_only:
type:
- 'null'
- boolean
description: Whether the campaign is text only
example: false
first_email_text_only:
type:
- 'null'
- boolean
description: Whether the campaign is send the first email as a text only
example: false
email_list:
type: array
description: List of accounts to use for sending emails
items:
type: string
example: john@doe.com
daily_limit:
type:
- 'null'
- number
description: The daily limit for sending emails
example: 100
stop_on_reply:
type:
- 'null'
- boolean
description: Whether to stop the campaign on reply
example: false
email_tag_list:
type: array
description: List of tags to use for sending emails
items:
type: string
format: uuid
example: 019ffad2-5c4b-761a-9bc4-059ac4b3a8a9
link_tracking:
type:
- 'null'
- boolean
description: Whether to track links in emails
example: true
open_tracking:
type: boolean
description: Whether to track opens in emails
example: true
stop_on_auto_reply:
type:
- 'null'
- boolean
description: Whether to stop the campaign on auto reply
example: false
daily_max_leads:
type:
- 'null'
- integer
description: The daily maximum new leads to contact
minimum: 0
example: 100
prioritize_new_leads:
type:
- 'null'
- boolean
description: Whether to prioritize new leads
example: false
auto_variant_select:
type:
- 'null'
- object
description: Auto variant select settings
properties:
trigger:
type: string
enum:
- reply_rate
- click_rate
- open_rate
examples:
- click_rate
example: click_rate
required:
- trigger
match_lead_esp:
type:
- 'null'
- boolean
description: Whether to match leads by ESP
example: false
not_sending_status:
type:
- 'null'
- number
description: Campaign not sending status
readOnly: true
enum:
- 1
- 2
- 3
- 4
- 99
x-enumDescriptions:
'1': Campaign is currently not within its sending schedule.
'2': Campaign is currently waiting for a lead to process.
'3': Campaign has reached its daily sending limit.
'4': All sending accounts for this campaign have reached their daily sending limit.
'99': Campaign is currently not sending due to an error. Please contact support for assistance.
example: 2
stop_for_company:
type:
- 'null'
- boolean
description: Whether to stop the campaign for the entire company(domain) when a lead replies
example: false
core_variables:
type:
- 'null'
- object
description: Campaign core variables
readOnly: true
additionalProperties: true
custom_variables:
type:
- 'null'
- object
description: Campaign custom variables
readOnly: true
additionalProperties: true
insert_unsubscribe_header:
type:
- 'null'
- boolean
description: Whether to insert an unsubscribe header in emails
example: false
allow_risky_contacts:
type:
- 'null'
- boolean
description: Whether to allow risky contacts
example: false
disable_bounce_protect:
type:
- 'null'
- boolean
description: Whether to disable bounce protection
example: false
limit_emails_per_company_override:
type:
- 'null'
- object
description: Overrides the workspace-wide limit emails per company setting for this campaign.
properties:
mode:
type: string
enum:
- custom
- disabled
examples:
- custom
example: custom
daily_limit:
type: number
minimum: 1
examples:
- 3
example: 3
scope:
type: string
enum:
- per_campaign
- across_workspace
examples:
- per_campaign
example: per_campaign
required:
- mode
cc_list:
type: array
description: List of accounts to CC on emails
items:
type: string
format: email
example: john@doe.com
bcc_list:
type: array
description: List of accounts to BCC on emails
items:
type: string
format: email
example: john@doe.com
organization:
type:
- 'null'
- string
description: Organization ID
readOnly: true
format: uuid
example: 019ffad2-5c4b-761a-9bc4-059bb9fa11bf
owned_by:
type:
- 'null'
- string
description: Owner ID
format: uuid
example: 019ffad2-5c4b-761a-9bc4-059c036e479a
ai_sdr_id:
type:
- 'null'
- string
description: AI Sales Agent ID that created this campaign
format: uuid
example: 019ffad2-5c4b-761a-9bc4-059dc9a58653
provider_routing_rules:
type: array
description: Auto variant select settings
items:
type: object
properties:
action:
type: string
enum:
- send
- do_not_send
example: send
recipient_esp:
type: array
items:
type: string
enum:
- all
- google
- outlook
- other
example: all
sender_esp:
type: array
items:
type: string
enum:
- all
- google
- outlook
- other
example: all
required:
- action
- recipient_esp
- sender_esp
required:
- id
- name
- status
- campaign_schedule
- timestamp_created
- timestamp_updated
additionalProperties: false
Email:
title: Email
description: A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox
x-tags:
- Schemas
- Email
type: object
properties:
id:
type: string
description: A Unique identifier
readOnly: true
format: uuid
example: 019ffad2-5c98-7531-9735-e1a09d243ff0
timestamp_created:
type: string
description: Timestamp when the email was added to our database. This is not the timestamp of the email itself,
since the email could have been sent at a different time. Please check the `timestamp_email` field for the timestamp
of the email.
readOnly: true
format: date-time
example: '2026-08-13T11:11:58.104Z'
timestamp_email:
type: string
description: The timestamp of the email, as provided by the email server. Please note that the timestamp is not
always accurate, as it can be manipulated by the sender or the email server.
readOnly: true
format: date-time
example: '2026-08-13T11:11:58.104Z'
message_id:
type: string
description: Unique email ID from the email server
readOnly: true
example: <example123@mail.gmail.com>
subject:
type: string
description: Subject line of the email message
example: 'Re: Your inquiry'
from_address_email:
type:
- 'null'
- string
description: The sender email address, populated based on the eaccount
readOnly: true
format: email
example: sender@example.com
to_address_email_list:
type: string
description: Comma-separated list of recipient email addresses
example: recipient@example.com
cc_address_email_list:
type:
- 'null'
- string
description: Comma-separated list of CC email addresses
example: cc@example.com
bcc_address_email_list:
type:
- 'null'
- string
description: Comma-separated list of BCC email addresses
example: bcc@example.com
reply_to:
type:
- 'null'
- string
description: Reply-to email address
example: replyto@example.com
body:
type: object
description: An object containing the email body in HTML and text format
readOnly: true
properties:
text:
type: string
description: Plain-text representation of the email body. Newline characters are preserved as line breaks in
this text view.
example: This is a test email
html:
type: string
description: HTML content of the email. Use `<br/>` tags for delivered email line breaks.
example: This is a test email.<br/><br/>Second line.
organization_id:
type: string
description: The workspace ID
readOnly: true
format: uuid
example: 019ffad2-5c98-7531-9735-e1a19020dfa8
campaign_id:
type:
- 'null'
- string
description: The id of the campaign that the email is associated with (it can be null for manually sent emails)
format: uuid
example: 019ffad2-5c98-7531-9735-e1a2d5f98274
subsequence_id:
type:
- 'null'
- string
description: The id of the campaign subsequence that the email is
# --- truncated at 32 KB (1702 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instantly-ai/refs/heads/main/openapi/instantly-ai-api-v2-openapi.yml