# Create account
Source: https://developer.instantly.ai/api-reference/account/create-account
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts
Requires one of the following scopes: `accounts:create`, `accounts:all`, `all:create`, `all:all`
# Delete account
Source: https://developer.instantly.ai/api-reference/account/delete-account
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/accounts/{email}
Requires one of the following scopes: `accounts:delete`, `accounts:all`, `all:delete`, `all:all`
# Disable warmup for accounts
Source: https://developer.instantly.ai/api-reference/account/disable-warmup-for-accounts
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/warmup/disable
Initiates a background job to disable warmup for the specified accounts. The response will contain the initial background job object. You can monitor the job's progress by polling the `GET: /api/v2/background-jobs/:id` endpoint.
# Enable warmup for accounts
Source: https://developer.instantly.ai/api-reference/account/enable-warmup-for-accounts
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/warmup/enable
Initiates a background job to enable warmup for the specified accounts. The response will contain the initial background job object. You can monitor the job's progress by polling the `GET: /api/v2/background-jobs/:id` endpoint.
# Get account
Source: https://developer.instantly.ai/api-reference/account/get-account
https://api.instantly.ai/openapi/api_v2.json get /api/v2/accounts/{email}
Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`
# Get custom tracking domain status
Source: https://developer.instantly.ai/api-reference/account/get-custom-tracking-domain-status
https://api.instantly.ai/openapi/api_v2.json get /api/v2/accounts/ctd/status
Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`
# Get daily account analytics
Source: https://developer.instantly.ai/api-reference/account/get-daily-account-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/accounts/analytics/daily
Get daily account analytics showing the number of emails sent per day for each email account. Useful for tracking daily sending activity across your accounts.
# Get warmup analytics
Source: https://developer.instantly.ai/api-reference/account/get-warmup-analytics
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/warmup-analytics
Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`
# List account
Source: https://developer.instantly.ai/api-reference/account/list-account
https://api.instantly.ai/openapi/api_v2.json get /api/v2/accounts
Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`
# Mark an account as fixed
Source: https://developer.instantly.ai/api-reference/account/mark-an-account-as-fixed
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/{email}/mark-fixed
Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`
# Move accounts between workspaces
Source: https://developer.instantly.ai/api-reference/account/move-accounts-between-workspaces
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/move
Move accounts between workspaces. IMPORTANT: this endpoint should be called ONLY with an ADMIN workspace API key (check the workspace group docs: https://developer.instantly.ai/workspace-group), and both the source and destination workspaces must have the same admin workspace.
# Patch account
Source: https://developer.instantly.ai/api-reference/account/patch-account
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/accounts/{email}
Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`
# Pause an account
Source: https://developer.instantly.ai/api-reference/account/pause-an-account
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/{email}/pause
Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`
# Pause multiple accounts
Source: https://developer.instantly.ai/api-reference/account/pause-multiple-accounts
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/pause
Pauses up to 100 email accounts in the authenticated workspace. Each unique email is returned in either `paused_emails` or `failed_emails`.
Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`
# Resume a paused account
Source: https://developer.instantly.ai/api-reference/account/resume-a-paused-account
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/{email}/resume
Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`
# Test account vitals
Source: https://developer.instantly.ai/api-reference/account/test-account-vitals
https://api.instantly.ai/openapi/api_v2.json post /api/v2/accounts/test/vitals
Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`
# Get campaigns associated with an email
Source: https://developer.instantly.ai/api-reference/accountcampaignmapping/get-campaigns-associated-with-an-email
https://api.instantly.ai/openapi/api_v2.json get /api/v2/account-campaign-mappings/{email}
Requires one of the following scopes: `account_campaign_mappings:read`, `account_campaign_mappings:all`, `all:read`, `all:all`
# Create api key
Source: https://developer.instantly.ai/api-reference/apikey/create-api-key
https://api.instantly.ai/openapi/api_v2.json post /api/v2/api-keys
Requires one of the following scopes: `api_keys:create`, `api_keys:all`, `all:create`, `all:all`
# Delete api key
Source: https://developer.instantly.ai/api-reference/apikey/delete-api-key
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/api-keys/{id}
Requires one of the following scopes: `api_keys:delete`, `api_keys:all`, `all:delete`, `all:all`
# List api key
Source: https://developer.instantly.ai/api-reference/apikey/list-api-key
https://api.instantly.ai/openapi/api_v2.json get /api/v2/api-keys
Requires one of the following scopes: `api_keys:read`, `api_keys:all`, `all:read`, `all:all`
# List audit log
Source: https://developer.instantly.ai/api-reference/auditlog/list-audit-log
https://api.instantly.ai/openapi/api_v2.json get /api/v2/audit-logs
Requires one of the following scopes: `audit_logs:read`, `audit_logs:all`, `all:read`, `all:all`
# Get background job
Source: https://developer.instantly.ai/api-reference/backgroundjob/get-background-job
https://api.instantly.ai/openapi/api_v2.json get /api/v2/background-jobs/{id}
Requires one of the following scopes: `background-jobs:read`, `background-jobs:all`, `all:read`, `all:all`
# List background job
Source: https://developer.instantly.ai/api-reference/backgroundjob/list-background-job
https://api.instantly.ai/openapi/api_v2.json get /api/v2/background-jobs
Requires one of the following scopes: `background-jobs:read`, `background-jobs:all`, `all:read`, `all:all`
# Bulk create block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/bulk-create-block-list-entry
https://api.instantly.ai/openapi/api_v2.json post /api/v2/block-lists-entries/bulk-create
Requires one of the following scopes: `block_list_entries:create`, `block_list_entries:all`, `all:create`, `all:all`
# Bulk delete block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/bulk-delete-block-list-entry
https://api.instantly.ai/openapi/api_v2.json post /api/v2/block-lists-entries/bulk-delete
Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`
# Create block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/create-block-list-entry
https://api.instantly.ai/openapi/api_v2.json post /api/v2/block-lists-entries
Requires one of the following scopes: `block_list_entries:create`, `block_list_entries:all`, `all:create`, `all:all`
# Delete all block list entries
Source: https://developer.instantly.ai/api-reference/blocklistentry/delete-all-block-list-entries
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/block-lists-entries
Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`
# Delete block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/delete-block-list-entry
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/block-lists-entries/{id}
Requires one of the following scopes: `block_list_entries:delete`, `block_list_entries:all`, `all:delete`, `all:all`
# Download all block list entries as CSV
Source: https://developer.instantly.ai/api-reference/blocklistentry/download-all-block-list-entries-as-csv
https://api.instantly.ai/openapi/api_v2.json get /api/v2/block-lists-entries/download
Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`
# Get block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/get-block-list-entry
https://api.instantly.ai/openapi/api_v2.json get /api/v2/block-lists-entries/{id}
Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`
# List block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/list-block-list-entry
https://api.instantly.ai/openapi/api_v2.json get /api/v2/block-lists-entries
Requires one of the following scopes: `block_list_entries:read`, `block_list_entries:all`, `all:read`, `all:all`
# Patch block list entry
Source: https://developer.instantly.ai/api-reference/blocklistentry/patch-block-list-entry
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/block-lists-entries/{id}
Requires one of the following scopes: `block_list_entries:update`, `block_list_entries:all`, `all:update`, `all:all`
# Activate(start), or resume a campaign
Source: https://developer.instantly.ai/api-reference/campaign/activatestart-or-resume-a-campaign
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/activate
Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`
# Add campaign variables
Source: https://developer.instantly.ai/api-reference/campaign/add-campaign-variables
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/variables
Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`
# Create campaign
Source: https://developer.instantly.ai/api-reference/campaign/create-campaign
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns
Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`
# Create campaign from shared one
Source: https://developer.instantly.ai/api-reference/campaign/create-campaign-from-shared-one
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/from-export
Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`
# Delete campaign
Source: https://developer.instantly.ai/api-reference/campaign/delete-campaign
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/campaigns/{id}
Requires one of the following scopes: `campaigns:delete`, `campaigns:all`, `all:delete`, `all:all`
# Duplicate campaign
Source: https://developer.instantly.ai/api-reference/campaign/duplicate-campaign
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/duplicate
Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`
# Export campaign to JSON format
Source: https://developer.instantly.ai/api-reference/campaign/export-campaign-to-json-format
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/export
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# Get campaign
Source: https://developer.instantly.ai/api-reference/campaign/get-campaign
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/{id}
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# Get campaign sending status
Source: https://developer.instantly.ai/api-reference/campaign/get-campaign-sending-status
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/{id}/sending-status
Returns sending status data explaining why a campaign may not be sending emails or is sending slower than expected. Note: Some fields may be missing when the campaign is out of schedule. Always-present fields: campaign_id, last_updated, status, issue_tracking.
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# Get campaign steps analytics
Source: https://developer.instantly.ai/api-reference/campaign/get-campaign-steps-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/analytics/steps
Get campaign steps analytics
# Get campaign(s) analytics
Source: https://developer.instantly.ai/api-reference/campaign/get-campaigns-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/analytics
Get analytics for one or multiple campaigns. Specify the `id` field to get the analytics for a single campaign, or leave it empty to get the analytics for all campaigns
# Get campaign(s) analytics overview
Source: https://developer.instantly.ai/api-reference/campaign/get-campaigns-analytics-overview
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/analytics/overview
Get analytics overview for one or multiple campaigns. Specify the `id` field to get the analytics overview for a single campaign, or leave it empty to get the analytics overview for all campaigns.
Note regarding the interest status totals (interested, meeting booked, meeting completed, closed): these are calculated based on the first occurrence of each event per contact by default. To change this behavior and calculate the totals based on all occurrences of the events, set the `expand_crm_events` parameter to `true`. Additionally, there is a 10 minute time window after you change a lead status in which the subsequent updates will NOT insert new analytics events to avoid duplicates from rapid status changes and avoid false inflation of the analytics numbers.
# Get daily campaign analytics
Source: https://developer.instantly.ai/api-reference/campaign/get-daily-campaign-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/analytics/daily
Get campaign daily analytics
# Get launched campaigns count
Source: https://developer.instantly.ai/api-reference/campaign/get-launched-campaigns-count
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/count-launched
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# List campaign
Source: https://developer.instantly.ai/api-reference/campaign/list-campaign
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# Patch campaign
Source: https://developer.instantly.ai/api-reference/campaign/patch-campaign
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/campaigns/{id}
Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`
# Search campaigns by lead email
Source: https://developer.instantly.ai/api-reference/campaign/search-campaigns-by-lead-email
https://api.instantly.ai/openapi/api_v2.json get /api/v2/campaigns/search-by-contact
Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`
# Share a campaign
Source: https://developer.instantly.ai/api-reference/campaign/share-a-campaign
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/share
Share a campaign. This allows other users to create new campaigns based on this campaign. The campaign is being shared for 7 days, after which you'll have to call this endpoint again if you want to enable sharing on the campaign
# Stop(or pause) a campaign
Source: https://developer.instantly.ai/api-reference/campaign/stopor-pause-a-campaign
https://api.instantly.ai/openapi/api_v2.json post /api/v2/campaigns/{id}/pause
Requires one of the following scopes: `campaigns:update`, `campaigns:all`, `all:update`, `all:all`
# Create campaign subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/create-campaign-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/subsequences
Requires one of the following scopes: `subsequences:create`, `subsequences:all`, `all:create`, `all:all`
# Delete campaign subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/delete-campaign-subsequence
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/subsequences/{id}
Requires one of the following scopes: `subsequences:delete`, `subsequences:all`, `all:delete`, `all:all`
# Duplicate a subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/duplicate-a-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/subsequences/{id}/duplicate
Duplicate a subsequence with the same trigger conditions
Requires one of the following scopes: `subsequences:create`, `subsequences:all`, `all:create`, `all:all`
# Get campaign subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/get-campaign-subsequence
https://api.instantly.ai/openapi/api_v2.json get /api/v2/subsequences/{id}
Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`
# Get subsequence analytics summary
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/get-subsequence-analytics-summary
https://api.instantly.ai/openapi/api_v2.json get /api/v2/subsequences/analytics
Returns per-subsequence engagement totals (emails sent, unique opens, unique replies) for the subsequences of a campaign.
Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`
# Get subsequence sending status
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/get-subsequence-sending-status
https://api.instantly.ai/openapi/api_v2.json get /api/v2/subsequences/{id}/sending-status
Returns sending status data explaining why a subsequence may not be sending emails or is sending slower than expected. Note: Some fields may be missing when the campaign is out of schedule. Always-present fields: campaign_id, subsequence_id, last_updated, status, issue_tracking.
Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`
# List campaign subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/list-campaign-subsequence
https://api.instantly.ai/openapi/api_v2.json get /api/v2/subsequences
Requires one of the following scopes: `subsequences:read`, `subsequences:all`, `all:read`, `all:all`
# Patch campaign subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/patch-campaign-subsequence
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/subsequences/{id}
Requires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`
# Pause a subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/pause-a-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/subsequences/{id}/pause
Pause a subsequence
Requires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`
# Resume a paused subsequence
Source: https://developer.instantly.ai/api-reference/campaignsubsequence/resume-a-paused-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/subsequences/{id}/resume
Resume a paused subsequence
Requires one of the following scopes: `subsequences:update`, `subsequences:all`, `all:update`, `all:all`
# Delete phone number
Source: https://developer.instantly.ai/api-reference/crmactions/delete-phone-number
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/crm-actions/phone-numbers/{id}
Delete a specific phone number from the organization.
Requires one of the following scopes: `crm_actions:delete`, `crm_actions:all`, `all:delete`, `all:all`
# List phone numbers
Source: https://developer.instantly.ai/api-reference/crmactions/list-phone-numbers
https://api.instantly.ai/openapi/api_v2.json get /api/v2/crm-actions/phone-numbers
Retrieve all phone numbers associated with the current organization.
Requires one of the following scopes: `crm_actions:read`, `crm_actions:all`, `all:read`, `all:all`
# Assign or unassign tags to resources
Source: https://developer.instantly.ai/api-reference/customtag/assign-or-unassign-tags-to-resources
https://api.instantly.ai/openapi/api_v2.json post /api/v2/custom-tags/toggle-resource
This can be used for both accounts and campaigns. Please check the `resource_type` field for more information.
# Create custom tag
Source: https://developer.instantly.ai/api-reference/customtag/create-custom-tag
https://api.instantly.ai/openapi/api_v2.json post /api/v2/custom-tags
Requires one of the following scopes: `custom_tags:create`, `custom_tags:all`, `all:create`, `all:all`
# Delete custom tag
Source: https://developer.instantly.ai/api-reference/customtag/delete-custom-tag
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/custom-tags/{id}
Requires one of the following scopes: `custom_tags:delete`, `custom_tags:all`, `all:delete`, `all:all`
# Get custom tag
Source: https://developer.instantly.ai/api-reference/customtag/get-custom-tag
https://api.instantly.ai/openapi/api_v2.json get /api/v2/custom-tags/{id}
Requires one of the following scopes: `custom_tags:read`, `custom_tags:all`, `all:read`, `all:all`
# List custom tag
Source: https://developer.instantly.ai/api-reference/customtag/list-custom-tag
https://api.instantly.ai/openapi/api_v2.json get /api/v2/custom-tags
Requires one of the following scopes: `custom_tags:read`, `custom_tags:all`, `all:read`, `all:all`
# Patch custom tag
Source: https://developer.instantly.ai/api-reference/customtag/patch-custom-tag
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/custom-tags/{id}
Requires one of the following scopes: `custom_tags:update`, `custom_tags:all`, `all:update`, `all:all`
# List custom tag mapping
Source: https://developer.instantly.ai/api-reference/customtagmapping/list-custom-tag-mapping
https://api.instantly.ai/openapi/api_v2.json get /api/v2/custom-tag-mappings
Requires one of the following scopes: `custom_tag_mappings:read`, `custom_tag_mappings:all`, `all:read`, `all:all`
# Cancel dfy email accounts
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/cancel-dfy-email-accounts
https://api.instantly.ai/openapi/api_v2.json post /api/v2/dfy-email-account-orders/accounts/cancel
This endpoint will cancel the DFY email accounts based on the provided email addresses. Cancelling permanently deletes all Unibox emails and conversations associated with the cancelled accounts. This cannot be undone.
Requires one of the following scopes: `dfy_email_account_orders:delete`, `dfy_email_account_orders:all`, `all:delete`, `all:all`
# Check domains availability
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/check-domains-availability
https://api.instantly.ai/openapi/api_v2.json post /api/v2/dfy-email-account-orders/domains/check
This endpoint will check the availability of the provided domains.. It will return a list of domains with their availability status.
. The only supported extensions (tlds) are: .com, .org.
. Domains containing trademarks of well-known companies are restricted and cannot be ordered.
. Please do not abuse this endpoint and do not use it for anything other than checking availability before ordering a domain.. This request has a rate limit of 30 request per minute, or 900 requests per hour.
Requires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`
# Generate similar available domains
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/generate-similar-available-domains
https://api.instantly.ai/openapi/api_v2.json post /api/v2/dfy-email-account-orders/domains/similar
This endpoint will generate a list of similar AND available domains based on the provided domain.. It will return a maximum number of 67 suggestions per extension (tld) requested.. All the returned domains will be available for order.. Domains containing trademarks of well-known companies are restricted and cannot be ordered.
Requires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`
# Get pre-warmed up domains
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/get-pre-warmed-up-domains
https://api.instantly.ai/openapi/api_v2.json post /api/v2/dfy-email-account-orders/domains/pre-warmed-up-list
This endpoint will return a list of pre-warmed up domains available for order.
These domains are set up and configured in advance, allowing for quick deployment of email services.
Use this endpoint to retrieve available pre-warmed up domains before placing an order.
IMPORTANT: if the endpoint returns a list of empty domains - it's not a bug, please don't retry right away or report this as a bug - it simply means that there are no available pre-warmed up domains at the moment.
Requires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`
# List dfy email account order
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/list-dfy-email-account-order
https://api.instantly.ai/openapi/api_v2.json get /api/v2/dfy-email-account-orders
Requires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`
# List DFY ordered email accounts
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/list-dfy-ordered-email-accounts
https://api.instantly.ai/openapi/api_v2.json get /api/v2/dfy-email-account-orders/accounts
This endpoint will return a list of DFY email accounts ordered
Requires one of the following scopes: `dfy_email_account_orders:read`, `dfy_email_account_orders:all`, `all:read`, `all:all`
# Place a DFY email account order
Source: https://developer.instantly.ai/api-reference/dfyemailaccountorder/place-a-dfy-email-account-order
https://api.instantly.ai/openapi/api_v2.json post /api/v2/dfy-email-account-orders
Place a Done-For-You (DFY) email account order for your workspace.
**Order types**
- `dfy`: Buy new DFY accounts on new custom domains.
- `pre_warmed_up`: Buy available pre-warmed domains returned by `/dfy-email-account-orders/domains/pre-warmed-up-list`.
- `extra_accounts`: Add mailboxes to domains you already ordered. All active accounts on a domain must use the same `email_provider`.
**Provider limits and pricing**
- `1` Google: up to 5 mailboxes per domain; per-mailbox monthly pricing.
- `2` AirMail: up to 5 mailboxes per domain; per-mailbox monthly pricing.
- `3` Microsoft/Outlook: 50-100 mailboxes per new DFY domain; per-domain monthly pricing; extra-account orders are not supported.
**Before ordering**
- Regular DFY domains must use supported TLDs: .com, .org.
- Check new-domain availability with `/dfy-email-account-orders/domains/check`.
- Domains containing trademarks of well-known companies are restricted and cannot be ordered.
- For pre-warmed orders, choose a domain from `/dfy-email-account-orders/domains/pre-warmed-up-list`; if none are available, use a regular `dfy` order instead.
- The workspace must have an active free trial, paid CRM plan, or Outreach entitlement, and a default payment method.
Requires one of the following scopes: `dfy_email_account_orders:create`, `dfy_email_account_orders:all`, `all:create`, `all:all`
# Count unread emails
Source: https://developer.instantly.ai/api-reference/email/count-unread-emails
https://api.instantly.ai/openapi/api_v2.json get /api/v2/emails/unread/count
Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`
# Delete email
Source: https://developer.instantly.ai/api-reference/email/delete-email
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/emails/{id}
Requires one of the following scopes: `emails:delete`, `emails:all`, `all:delete`, `all:all`
# Forward an email
Source: https://developer.instantly.ai/api-reference/email/forward-an-email
https://api.instantly.ai/openapi/api_v2.json post /api/v2/emails/forward
Forward an existing email to another recipient. You must specify the `reply_to_uuid` field, which represents the `id` of an existing email returned by the `/emails` endpoints. By default only the provided body is sent. Set `include_original_body` to `true` to append the original email context.
Requires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`
# Get email
Source: https://developer.instantly.ai/api-reference/email/get-email
https://api.instantly.ai/openapi/api_v2.json get /api/v2/emails/{id}
Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`
# List email
Source: https://developer.instantly.ai/api-reference/email/list-email
https://api.instantly.ai/openapi/api_v2.json get /api/v2/emails
**Rate Limit:** This endpoint has a rate limit of 20 requests per minute, unlike other API endpoints.
Requires one of the following scopes: `emails:read`, `emails:all`, `all:read`, `all:all`
# Mark all emails in a thread as read
Source: https://developer.instantly.ai/api-reference/email/mark-all-emails-in-a-thread-as-read
https://api.instantly.ai/openapi/api_v2.json post /api/v2/emails/threads/{thread_id}/mark-as-read
Requires one of the following scopes: `emails:update`, `emails:all`, `all:update`, `all:all`
# Patch email
Source: https://developer.instantly.ai/api-reference/email/patch-email
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/emails/{id}
Requires one of the following scopes: `emails:update`, `emails:all`, `all:update`, `all:all`
# Reply to an email
Source: https://developer.instantly.ai/api-reference/email/reply-to-an-email
https://api.instantly.ai/openapi/api_v2.json post /api/v2/emails/reply
Send a reply to an email. This endpoint can be used to send an email only as a reply to an existing email. In order to reply to an email, please specify the `reyply_to_uuid` field, and your email will be sent as a reply to that email. The `reyply_to_uuid` field represents the `id` field of an existing email, which is being returned to you in all the `/email` endpoints
Requires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`
# Send a test email
Source: https://developer.instantly.ai/api-reference/email/send-a-test-email
https://api.instantly.ai/openapi/api_v2.json post /api/v2/emails/test
Send a preview/test email without creating an email entity in Unibox. Rate limit: 10 requests per minute per workspace.
Requires one of the following scopes: `emails:create`, `emails:all`, `all:create`, `all:all`
# Check an email verification status
Source: https://developer.instantly.ai/api-reference/emailverification/check-an-email-verification-status
https://api.instantly.ai/openapi/api_v2.json get /api/v2/email-verification/{email}
Requires one of the following scopes: `email_verifications:read`, `email_verifications:all`, `all:read`, `all:all`
# Create email verification
Source: https://developer.instantly.ai/api-reference/emailverification/create-email-verification
https://api.instantly.ai/openapi/api_v2.json post /api/v2/email-verification
If an email takes longer than 10 seconds to verify, the endpoint will return the status as `pending`. In that case, you may use the `/email-verification/:email` endpoint to check the status of the verification job.
Alternatively, you can send a `webhook_url` to receive the results instead of polling the status endpoint.
Requires one of the following scopes: `email_verifications:create`
Requires one of the following scopes: `email_verifications:create`, `email_verifications:all`, `all:create`, `all:all`
# Get inbox placement analytics
Source: https://developer.instantly.ai/api-reference/inboxplacementanalytics/get-inbox-placement-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-analytics/{id}
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`
# Get inbox placement analytics stats by date
Source: https://developer.instantly.ai/api-reference/inboxplacementanalytics/get-inbox-placement-analytics-stats-by-date
https://api.instantly.ai/openapi/api_v2.json post /api/v2/inbox-placement-analytics/stats-by-date
Provides a time series representing the distribution of emails sent to inbox, spam, or category folders for scheduled inbox placement tests.
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`
# List inbox placement analytics
Source: https://developer.instantly.ai/api-reference/inboxplacementanalytics/list-inbox-placement-analytics
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-analytics
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`
# Retrieve inbox placement analytics deliverability insights
Source: https://developer.instantly.ai/api-reference/inboxplacementanalytics/retrieve-inbox-placement-analytics-deliverability-insights
https://api.instantly.ai/openapi/api_v2.json post /api/v2/inbox-placement-analytics/deliverability-insights
Provides deliverability insights for a specific inbox placement test
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`
# Retrieve inbox placement analytics stats by test id
Source: https://developer.instantly.ai/api-reference/inboxplacementanalytics/retrieve-inbox-placement-analytics-stats-by-test-id
https://api.instantly.ai/openapi/api_v2.json post /api/v2/inbox-placement-analytics/stats-by-test-id
Provides aggregated inbox, spam and category counts for specified test IDs
Requires one of the following scopes: `inbox_placement_analytics:read`, `inbox_placement_analytics:all`, `all:read`, `all:all`
# Get inbox placement blacklist and spamassassin report
Source: https://developer.instantly.ai/api-reference/inboxplacementblacklistandspamassassinreport/get-inbox-placement-blacklist-and-spamassassin-report
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-reports/{id}
Requires one of the following scopes: `inbox_placement_reports:read`, `inbox_placement_reports:all`, `all:read`, `all:all`
# List inbox placement blacklist and spamassassin report
Source: https://developer.instantly.ai/api-reference/inboxplacementblacklistandspamassassinreport/list-inbox-placement-blacklist-and-spamassassin-report
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-reports
Requires one of the following scopes: `inbox_placement_reports:read`, `inbox_placement_reports:all`, `all:read`, `all:all`
# Create inbox placement test
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/create-inbox-placement-test
https://api.instantly.ai/openapi/api_v2.json post /api/v2/inbox-placement-tests
Requires one of the following scopes: `inbox_placement_tests:create`, `inbox_placement_tests:all`, `all:create`, `all:all`
# Delete inbox placement test
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/delete-inbox-placement-test
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/inbox-placement-tests/{id}
Requires one of the following scopes: `inbox_placement_tests:delete`, `inbox_placement_tests:all`, `all:delete`, `all:all`
# Get ESP options
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/get-esp-options
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-tests/email-service-provider-options
Provides a list of available email service providers for inbox placement tests.
# Get inbox placement test
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/get-inbox-placement-test
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-tests/{id}
Requires one of the following scopes: `inbox_placement_tests:read`, `inbox_placement_tests:all`, `all:read`, `all:all`
# List inbox placement test
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/list-inbox-placement-test
https://api.instantly.ai/openapi/api_v2.json get /api/v2/inbox-placement-tests
Requires one of the following scopes: `inbox_placement_tests:read`, `inbox_placement_tests:all`, `all:read`, `all:all`
# Patch inbox placement test
Source: https://developer.instantly.ai/api-reference/inboxplacementtest/patch-inbox-placement-test
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/inbox-placement-tests/{id}
Requires one of the following scopes: `inbox_placement_tests:update`, `inbox_placement_tests:all`, `all:update`, `all:all`
# Introduction
Source: https://developer.instantly.ai/api-reference/introduction
This documentation is for the second version of the Instantly API.
## What's new
The second version with the API comes with a lot of improvements:
1. API Scopes offer enhanced security and control over the API keys and how they're being used.
2. Double the amount of endpoints as compared to V1.
3. Strict adherence to REST API Standards.
4. Follows strict naming rules for entities, fields (snake\_case), etc.
## V1 compatibility
* The first version of the API will still be available and maintained for a while, but we plan to deprecate it in 2025, so please migrate to API V2 as soon as possible.
* The second version of the API has NO compatibility with the first version of the API. You will need a new API key to use the API V2 endpoints.
### Authentication
We are using Bearer token authentication, which is more secure than the previous version authentication.
### Multiple API keys
It's possible to create multiple API keys, which can be revoked, improving the security.
### API scopes
We're introducing API scopes, which can be used to offer granular control for each API key.
### REST endpoints
The second version of the API is adhering to the REST API standards, with a few minor exceptions.
# Add leads in bulk to a campaign or list
Source: https://developer.instantly.ai/api-reference/lead/add-leads-in-bulk-to-a-campaign-or-list
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/add
Adds up to 1000 leads to either a campaign or a list. You must provide a `campaign_id` or a `list_id`, but not both. The endpoint validates emails, checks against blocklists and existing leads.
Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`
# Bulk assign leads to organization users
Source: https://developer.instantly.ai/api-reference/lead/bulk-assign-leads-to-organization-users
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/bulk-assign
Bulk assign leads to organization users
# Create lead
Source: https://developer.instantly.ai/api-reference/lead/create-lead
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads
Requires one of the following scopes: `leads:create`, `leads:all`, `all:create`, `all:all`
# Delete lead
Source: https://developer.instantly.ai/api-reference/lead/delete-lead
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/leads/{id}
Requires one of the following scopes: `leads:delete`, `leads:all`, `all:delete`, `all:all`
# Delete leads in bulk
Source: https://developer.instantly.ai/api-reference/lead/delete-leads-in-bulk
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/leads
Delete multiple leads from a campaign or list based on filters. You must provide either `campaign_id` or `list_id`. Optionally filter by status or specific IDs.
Requires one of the following scopes: `leads:delete`, `leads:all`, `all:delete`, `all:all`
# Get lead
Source: https://developer.instantly.ai/api-reference/lead/get-lead
https://api.instantly.ai/openapi/api_v2.json get /api/v2/leads/{id}
Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`
# List leads
Source: https://developer.instantly.ai/api-reference/lead/list-leads
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/list
This endpoint is a POST endpoint, instead of GET - a deviation from the REST APIs standards we’re following because of the complex arguments it accepts, which would be too hard to express through query parameters. Results are ordered by each lead's `id` field in ascending order (or by `contact` when distinct_contacts is true) so clients can paginate chronologically by reusing the cursor returned in `next_starting_after`. Leads created on or after October 15, 2025 respect this chronological ordering; older records may appear out of sequence when sorted by ID.
Requires one of the following scopes: `leads:read`, `leads:all`, `all:read`, `all:all`
# Merge two leads
Source: https://developer.instantly.ai/api-reference/lead/merge-two-leads
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/merge
Merge two leads
Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`
# Move a lead to a subsequence
Source: https://developer.instantly.ai/api-reference/lead/move-a-lead-to-a-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/subsequence/move
Move a lead to a subsequence
Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`
# Move leads to a campaign or list
Source: https://developer.instantly.ai/api-reference/lead/move-leads-to-a-campaign-or-list
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/move
Move leads to a different campaign or list. This endpoint will return a background job that will process the move. The job will be processed in the background and the leads will be moved to the destination campaign or list. You can use the `/background-jobs/:id` endpoint to check the job status. Note: When using the `ids` parameter, you must also provide either `campaign` or `list_id` to specify which campaign or list to filter the leads from.
Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`
# Patch lead
Source: https://developer.instantly.ai/api-reference/lead/patch-lead
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/leads/{id}
Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`
# Remove a lead from a subsequence
Source: https://developer.instantly.ai/api-reference/lead/remove-a-lead-from-a-subsequence
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/subsequence/remove
Remove a lead from a subsequence
Requires one of the following scopes: `leads:update`, `leads:all`, `all:update`, `all:all`
# Update the interest status of a lead
Source: https://developer.instantly.ai/api-reference/lead/update-the-interest-status-of-a-lead
https://api.instantly.ai/openapi/api_v2.json post /api/v2/leads/update-interest-status
Update the interest status of a lead
# Create lead label
Source: https://developer.instantly.ai/api-reference/leadlabel/create-lead-label
https://api.instantly.ai/openapi/api_v2.json post /api/v2/lead-labels
Requires one of the following scopes: `lead-labels:create`, `lead-labels:all`, `all:create`, `all:all`
# Delete lead label
Source: https://developer.instantly.ai/api-reference/leadlabel/delete-lead-label
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/lead-labels/{id}
Requires one of the following scopes: `lead-labels:delete`, `lead-labels:all`, `all:delete`, `all:all`
# Get lead label
Source: https://developer.instantly.ai/api-reference/leadlabel/get-lead-label
https://api.instantly.ai/openapi/api_v2.json get /api/v2/lead-labels/{id}
Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`
# List lead label
Source: https://developer.instantly.ai/api-reference/leadlabel/list-lead-label
https://api.instantly.ai/openapi/api_v2.json get /api/v2/lead-labels
Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`
# Patch lead label
Source: https://developer.instantly.ai/api-reference/leadlabel/patch-lead-label
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/lead-labels/{id}
Requires one of the following scopes: `lead-labels:update`, `lead-labels:all`, `all:update`, `all:all`
# Test AI reply label prediction
Source: https://developer.instantly.ai/api-reference/leadlabel/test-ai-reply-label-prediction
https://api.instantly.ai/openapi/api_v2.json post /api/v2/lead-labels/ai-reply-label
Returns the AI-predicted lead label for a reply text. This simulates how AI auto-tagging would label an incoming reply for testing custom labels and descriptions. Rate limit: 500 requests per 30 days per workspace. This rate limit applies only to this testing endpoint; live reply processing does not use this limiter.
Requires one of the following scopes: `lead-labels:read`, `lead-labels:all`, `all:read`, `all:all`
# Create lead list
Source: https://developer.instantly.ai/api-reference/leadlist/create-lead-list
https://api.instantly.ai/openapi/api_v2.json post /api/v2/lead-lists
Requires one of the following scopes: `lead_lists:create`, `lead_lists:all`, `all:create`, `all:all`
# Delete lead list
Source: https://developer.instantly.ai/api-reference/leadlist/delete-lead-list
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/lead-lists/{id}
Requires one of the following scopes: `lead_lists:delete`, `lead_lists:all`, `all:delete`, `all:all`
# Get lead list
Source: https://developer.instantly.ai/api-reference/leadlist/get-lead-list
https://api.instantly.ai/openapi/api_v2.json get /api/v2/lead-lists/{id}
Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`
# Get verification statistics for a lead list
Source: https://developer.instantly.ai/api-reference/leadlist/get-verification-statistics-for-a-lead-list
https://api.instantly.ai/openapi/api_v2.json get /api/v2/lead-lists/{id}/verification-stats
Get verification statistics for a lead list
# List lead list
Source: https://developer.instantly.ai/api-reference/leadlist/list-lead-list
https://api.instantly.ai/openapi/api_v2.json get /api/v2/lead-lists
Requires one of the following scopes: `lead_lists:read`, `lead_lists:all`, `all:read`, `all:all`
# Patch lead list
Source: https://developer.instantly.ai/api-reference/leadlist/patch-lead-list
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/lead-lists/{id}
Requires one of the following scopes: `lead_lists:update`, `lead_lists:all`, `all:update`, `all:all`
# Get oauth session status
Source: https://developer.instantly.ai/api-reference/oauth/get-oauth-session-status
https://api.instantly.ai/openapi/api_v2.json get /api/v2/oauth/session/status/{sessionId}
Poll this endpoint to check the OAuth session result. Works for both Google and Microsoft OAuth sessions. Returns pending while waiting, success with account details when complete, or error if something went wrong. Sessions expire after 10 minutes.
# Initialize google oauth
Source: https://developer.instantly.ai/api-reference/oauth/initialize-google-oauth
https://api.instantly.ai/openapi/api_v2.json post /api/v2/oauth/google/init
Creates an OAuth session and returns the Google authorization URL. The user should be redirected to auth_url to complete the OAuth flow. Poll the status endpoint to check for completion.
**Special rate limits (stricter than the standard API rate limit) to comply with upstream Google rate limits:**
- 75 requests per minute per workspace
- 150 requests per minute per IP
If Google's upstream OAuth service is temporarily unavailable, requests may return 503.
# Initialize microsoft oauth
Source: https://developer.instantly.ai/api-reference/oauth/initialize-microsoft-oauth
https://api.instantly.ai/openapi/api_v2.json post /api/v2/oauth/microsoft/init
Creates an OAuth session and returns the Microsoft authorization URL. The user should be redirected to auth_url to complete the OAuth flow. Poll the status endpoint to check for completion.
**Special rate limits (stricter than the standard API rate limit) to comply with upstream Microsoft rate limits:**
- 75 requests per minute per workspace
- 150 requests per minute per IP
If Microsoft's upstream OAuth service is temporarily unavailable, requests may return 503.
# Schemas
Source: https://developer.instantly.ai/api-reference/schemas/index
Browse all API data models and their field definitions.
This section documents the data models used across the Instantly API v2. Schemas are grouped by the resource domain they belong to.
## Accounts & email
| Schema | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [Account](/api-reference/schemas/account) | An email account that can be used to send campaigns |
| [Email](/api-reference/schemas/email) | A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox |
| [Email Verification](/api-reference/schemas/email-verification) | A single email verification |
| [Account Campaign Mapping](/api-reference/schemas/account-campaign-mapping) | Mapping between accounts and campaigns |
| [API Key](/api-reference/schemas/api-key) | API key for authentication |
## Campaigns & sequences
| Schema | Description |
| ------------------------------------------------------------------- | --------------------------------------------------- |
| [Campaign](/api-reference/schemas/campaign) | A campaign that can be sent to a list of recipients |
| [Campaign Subsequence](/api-reference/schemas/campaign-subsequence) | A follow-up sequence within a campaign |
## Leads & lists
| Schema | Description |
| ----------------------------------------------- | -------------------------------------------------- |
| [Lead](/api-reference/schemas/lead) | A lead entity representing an individual lead |
| [Lead List](/api-reference/schemas/lead-list) | A list used to store leads |
| [Lead Label](/api-reference/schemas/lead-label) | A custom label for categorizing and managing leads |
## Tags & blocking
| Schema | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------------- |
| [Custom Tag](/api-reference/schemas/custom-tag) | A custom tag for organizing and categorizing accounts and campaigns |
| [Custom Tag Mapping](/api-reference/schemas/custom-tag-mapping) | A tag assignment connecting a tag to a campaign or email account |
| [Block List Entry](/api-reference/schemas/block-list-entry) | A blocked email or domain |
## Inbox placement
| Schema | Description |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [Inbox Placement Test](/api-reference/schemas/inbox-placement-test) | An inbox placement test |
| [Inbox Placement Analytics](/api-reference/schemas/inbox-placement-analytics) | Analytics data for individual emails in inbox placement tests |
| [Inbox Placement Blacklist & SpamAssassin Report](/api-reference/schemas/inbox-placement-blacklist-spamassassin-report) | Report data for an inbox placement test |
## Webhooks
| Schema | Description |
| ----------------------------------------------------- | -------------------------------------------------------- |
| [Webhook](/api-reference/schemas/webhook) | A webhook subscription for receiving event notifications |
| [Webhook Event](/api-reference/schemas/webhook-event) | A webhook event that was sent or attempted to be sent |
## Workspace & members
| Schema | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| [Workspace](/api-reference/schemas/workspace) | A workspace entity representing a workspace |
| [Workspace Member](/api-reference/schemas/workspace-member) | A member of a workspace with associated user details |
| [Workspace Group Member](/api-reference/schemas/workspace-group-member) | A member of a workspace group |
| [Workspace Billing](/api-reference/schemas/workspace-billing) | Workspace billing details |
## Enrichment & provisioning
| Schema | Description |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| [SuperSearch Enrichment](/api-reference/schemas/supersearch-enrichment) | An enrichment for leads via email or LinkedIn data |
| [DFY Email Account Order](/api-reference/schemas/dfy-email-account-order) | A Done-For-You email account order |
## Other
| Schema | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Audit Log](/api-reference/schemas/audit-log) | Audit log records for tracking system activities |
| [Background Job](/api-reference/schemas/background-job) | A background job for long-running tasks |
| [CRM Actions](/api-reference/schemas/crm-actions) | CRM related actions |
| [Custom Prompt Template](/api-reference/schemas/custom-prompt-template) | Custom prompt templates for creating custom prompts |
| [Email Template](/api-reference/schemas/email-template) | A campaign email template |
| [Sales Flow](/api-reference/schemas/sales-flow) | Manages how sales users view and interact with campaign and lead lists |
# Count leads from supersearch
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/count-leads-from-supersearch
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/count-leads-from-supersearch
Count the number of leads matching a SuperSearch query without enriching them. This endpoint is intended to estimate lead availability before running an enrichment.
Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`
# Create AI enrichment
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/create-ai-enrichment
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/ai
Create an AI enrichment for a resource (list or campaign)
Requires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`
# Create an enrichment
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/create-an-enrichment
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/
Create an enrichment for a specific resource (list or campaign). This is the main endpoint for adding enrichments to resources. The enrichments are automatically run after creation.
# Enrich leads from supersearch
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/enrich-leads-from-supersearch
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/enrich-leads-from-supersearch
Add leads from SuperSearch to a list and enrich them. A list is automatically created if no list is provided.
# Facet keywords for a signal category
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/facet-keywords-for-a-signal-category
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/signal-keywords-facet
Return the top matching keyword tokens for a given signal category and keyword field, aggregated from the last 90 days of signal data. Powers the Signals filter autocomplete in the Lead Finder. Unknown (category, field) pairs return 400.
Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`
# Get AI enrichment for resource
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/get-ai-enrichment-for-resource
https://api.instantly.ai/openapi/api_v2.json get /api/v2/supersearch-enrichment/ai/{resource_id}/in-progress
Get the AI enrichment for a specific resource
Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`
# Get enrichment for resource
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/get-enrichment-for-resource
https://api.instantly.ai/openapi/api_v2.json get /api/v2/supersearch-enrichment/{resource_id}
Get the enrichment for a specific resource
# Get enrichment history
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/get-enrichment-history
https://api.instantly.ai/openapi/api_v2.json get /api/v2/supersearch-enrichment/history/{resource_id}
Retrieve the enrichment history for a specific resource
Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`
# Preview leads from supersearch
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/preview-leads-from-supersearch
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/preview-leads-from-supersearch
Preview the leads matching a SuperSearch query without enriching them
Requires one of the following scopes: `supersearch_enrichments:read`, `supersearch_enrichments:all`, `all:read`, `all:all`
# Run enrichment for resource
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/run-enrichment-for-resource
https://api.instantly.ai/openapi/api_v2.json post /api/v2/supersearch-enrichment/run
Run all enrichments associated with a resource for a list of leads or for all the leads that haven't been enriched yet
# Update enrichment settings for resource
Source: https://developer.instantly.ai/api-reference/supersearchenrichment/update-enrichment-settings-for-resource
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/supersearch-enrichment/{resource_id}/settings
Update auto-update and skip settings for a SuperSearch enrichment tied to a specific resource
Requires one of the following scopes: `supersearch_enrichments:create`, `supersearch_enrichments:all`, `all:create`, `all:all`
# Create webhook
Source: https://developer.instantly.ai/api-reference/webhook/create-webhook
https://api.instantly.ai/openapi/api_v2.json post /api/v2/webhooks
Requires one of the following scopes: `webhooks:create`, `webhooks:all`, `all:create`, `all:all`
# Delete webhook
Source: https://developer.instantly.ai/api-reference/webhook/delete-webhook
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/webhooks/{id}
Requires one of the following scopes: `webhooks:delete`, `webhooks:all`, `all:delete`, `all:all`
# Get webhook
Source: https://developer.instantly.ai/api-reference/webhook/get-webhook
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhooks/{id}
Requires one of the following scopes: `webhooks:read`, `webhooks:all`, `all:read`, `all:all`
# List available event types
Source: https://developer.instantly.ai/api-reference/webhook/list-available-event-types
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhooks/event-types
Get all available webhook event types including custom labels
# List webhooks
Source: https://developer.instantly.ai/api-reference/webhook/list-webhooks
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhooks
List all webhooks for the workspace with optional filters
# Patch webhook
Source: https://developer.instantly.ai/api-reference/webhook/patch-webhook
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/webhooks/{id}
Requires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`
# Resume a webhook
Source: https://developer.instantly.ai/api-reference/webhook/resume-a-webhook
https://api.instantly.ai/openapi/api_v2.json post /api/v2/webhooks/{id}/resume
Resume a webhook that was disabled due to repeated delivery failures
Requires one of the following scopes: `webhooks:update`, `webhooks:all`, `all:update`, `all:all`
# Test a webhook
Source: https://developer.instantly.ai/api-reference/webhook/test-a-webhook
https://api.instantly.ai/openapi/api_v2.json post /api/v2/webhooks/{id}/test
Send a test payload to a webhook URL to verify it is working
# Get overview aggregates for webhook events
Source: https://developer.instantly.ai/api-reference/webhookevent/get-overview-aggregates-for-webhook-events
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhook-events/summary
Get overview aggregates for webhook events including success/failure rates
# Get overview aggregates for webhook events by date
Source: https://developer.instantly.ai/api-reference/webhookevent/get-overview-aggregates-for-webhook-events-by-date
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhook-events/summary-by-date
Get overview aggregates for webhook events by Date for charts
# Get webhook event
Source: https://developer.instantly.ai/api-reference/webhookevent/get-webhook-event
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhook-events/{id}
Requires one of the following scopes: `webhook_events:read`, `webhook_events:all`, `all:read`, `all:all`
# List webhook event
Source: https://developer.instantly.ai/api-reference/webhookevent/list-webhook-event
https://api.instantly.ai/openapi/api_v2.json get /api/v2/webhook-events
Requires one of the following scopes: `webhook_events:read`, `webhook_events:all`, `all:read`, `all:all`
# Cancel Current Workspace Removal
Source: https://developer.instantly.ai/api-reference/workspace/cancel-current-workspace-removal
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/workspaces/current/schedule-for-removal
Requires one of the following scopes: `workspaces:delete`, `workspaces:all`, `all:delete`, `all:all`
# Change workspace owner
Source: https://developer.instantly.ai/api-reference/workspace/change-workspace-owner
https://api.instantly.ai/openapi/api_v2.json post /api/v2/workspaces/current/change-owner
Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`
# Delete organization agency domain
Source: https://developer.instantly.ai/api-reference/workspace/delete-organization-agency-domain
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/workspaces/current/whitelabel-domain
Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`
# Get organization verified agency domain information
Source: https://developer.instantly.ai/api-reference/workspace/get-organization-verified-agency-domain-information
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspaces/current/whitelabel-domain
Requires one of the following scopes: `workspaces:read`, `workspaces:all`, `all:read`, `all:all`
# Get workspace
Source: https://developer.instantly.ai/api-reference/workspace/get-workspace
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspaces/current
Get your current workspace details. Note that this endpoint doesn't require any parameters. It will return the workspace based on the API key sent in the headers.
Requires one of the following scopes: `workspaces:read`, `workspaces:all`, `all:read`, `all:all`
# Patch workspace
Source: https://developer.instantly.ai/api-reference/workspace/patch-workspace
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/workspaces/current
Update your current workspace details. Note that this endpoint doesn't require any parameters. It will update the workspace based on the API key sent in the headers.
Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`
# Schedule Current Workspace Removal
Source: https://developer.instantly.ai/api-reference/workspace/schedule-current-workspace-removal
https://api.instantly.ai/openapi/api_v2.json post /api/v2/workspaces/current/schedule-for-removal
Schedule the current workspace to be removed in 24 hours.
Requires one of the following scopes: `workspaces:delete`, `workspaces:all`, `all:delete`, `all:all`
# Set the agency domain for the workspace
Source: https://developer.instantly.ai/api-reference/workspace/set-the-agency-domain-for-the-workspace
https://api.instantly.ai/openapi/api_v2.json post /api/v2/workspaces/current/whitelabel-domain
Requires one of the following scopes: `workspaces:update`, `workspaces:all`, `all:update`, `all:all`
# Get workspace plan details
Source: https://developer.instantly.ai/api-reference/workspacebilling/get-workspace-plan-details
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-billing/plan-details
Requires one of the following scopes: `workspace_billing:read`, `workspace_billing:all`, `all:read`, `all:all`
# Get workspace subscription details
Source: https://developer.instantly.ai/api-reference/workspacebilling/get-workspace-subscription-details
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-billing/subscription-details
Requires one of the following scopes: `workspace_billing:read`, `workspace_billing:all`, `all:read`, `all:all`
# Create workspace group member
Source: https://developer.instantly.ai/api-reference/workspacegroupmember/create-workspace-group-member
https://api.instantly.ai/openapi/api_v2.json post /api/v2/workspace-group-members
This endpoint allows you to send an invitation for a sub workspace to join the admin workspace. The sub workspace will be added as a sub workspace of the admin workspace only if the sub workspace owner accepts the invitation.
Requires one of the following scopes: `workspace_group_members:create`, `workspace_group_members:all`, `all:create`, `all:all`
# Delete workspace group member
Source: https://developer.instantly.ai/api-reference/workspacegroupmember/delete-workspace-group-member
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/workspace-group-members/{id}
Requires one of the following scopes: `workspace_group_members:delete`, `workspace_group_members:all`, `all:delete`, `all:all`
# Get the current workspace admin workspace
Source: https://developer.instantly.ai/api-reference/workspacegroupmember/get-the-current-workspace-admin-workspace
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-group-members/admin
Get the details of the admin workspace of the current workspace
# Get workspace group member
Source: https://developer.instantly.ai/api-reference/workspacegroupmember/get-workspace-group-member
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-group-members/{id}
Requires one of the following scopes: `workspace_group_members:read`, `workspace_group_members:all`, `all:read`, `all:all`
# List workspace group member
Source: https://developer.instantly.ai/api-reference/workspacegroupmember/list-workspace-group-member
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-group-members
Requires one of the following scopes: `workspace_group_members:read`, `workspace_group_members:all`, `all:read`, `all:all`
# Create workspace member
Source: https://developer.instantly.ai/api-reference/workspacemember/create-workspace-member
https://api.instantly.ai/openapi/api_v2.json post /api/v2/workspace-members
Requires one of the following scopes: `workspace_members:create`, `workspace_members:all`, `all:create`, `all:all`
# Delete workspace member
Source: https://developer.instantly.ai/api-reference/workspacemember/delete-workspace-member
https://api.instantly.ai/openapi/api_v2.json delete /api/v2/workspace-members/{id}
Requires one of the following scopes: `workspace_members:delete`, `workspace_members:all`, `all:delete`, `all:all`
# Get workspace member
Source: https://developer.instantly.ai/api-reference/workspacemember/get-workspace-member
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-members/{id}
Requires one of the following scopes: `workspace_members:read`, `workspace_members:all`, `all:read`, `all:all`
# List workspace member
Source: https://developer.instantly.ai/api-reference/workspacemember/list-workspace-member
https://api.instantly.ai/openapi/api_v2.json get /api/v2/workspace-members
Requires one of the following scopes: `workspace_members:read`, `workspace_members:all`, `all:read`, `all:all`
# Patch workspace member
Source: https://developer.instantly.ai/api-reference/workspacemember/patch-workspace-member
https://api.instantly.ai/openapi/api_v2.json patch /api/v2/workspace-members/{id}
Requires one of the following scopes: `workspace_members:update`, `workspace_members:all`, `all:update`, `all:all`
# Authorization
Source: https://developer.instantly.ai/getting-started/authorization
Instantly API Authorization Guide
We are using [bearer token](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication) authorization.
You will need your API key (check the getting started section if you don't know how to create one).
Add a new `header` to your request, called `authorization`, with the value: `Bearer {{key}}` - where `key` is your API key.
# Getting Started
Source: https://developer.instantly.ai/getting-started/getting-started
Please read the guide below to get started with the second version of our API.
## Generate a new API key
First of all, you will need a new API key
To create a new key:
1. Go to [integrations](https://app.instantly.ai/app/settings/integrations)
2. Click the "API Keys" section in the left sidebar
3. Click the "Create API Key" button
4. Enter the API key name (used for display purposes only)
5. Select the scopes you would like this API key to have
6. Press the "Create" button
7. Copy the key and store it in a secure place
For security reasons, the API key will be displayed only once, and there is no way to recover it if you loose it.
You are ready to go now, proceed to the Authorization section to see how to use your API key.
# Rate Limit
Source: https://developer.instantly.ai/getting-started/rate-limit
Learn about the API rate limits and how to handle them.
The rate limit is shared between API v2 and API v1, and it applies to the entire Workspace, even if it's using multiple API keys.
The following rate limits are applied:
1. No more than 100 requests per second
2. No more than 6,000 requests per minute
Your requests will be blocked if you reach ANY of the limits above.
## Exceeding the limit
If you exceed the limit, the API requests will fail with the `429` status code.
## Staying within the limit
There are a few things that you can do to make sure you don't hit the limits:
### Run your automations multiple times a day
Instead of running some of your automated tasks once a day, and sending a lot of requests, try to do this 2-4 times a day, which will reduce the number of requests you send at once.
### Batch your API calls and apply a wait time between batches
Let's say you want to update 10,000 leads and you have to make 10,000 API calls. In this case, you should:
1. Batch the API calls in batches of 100 leads
2. Add a wait time of 2 seconds between the batches
3. Process the next batch
4. Repeat until you sent all the requests.
Please use ChatGPT, or any other LLM in case you need help to restructure your code to fit into our rate limits.
# Slack channel
Source: https://developer.instantly.ai/getting-started/slack-channel
Join the Instantly developer Slack community to discuss APIs, ask questions, and share feedback.
Our Slack channel is the go-to place for developers to discuss our APIs, ask questions, and provide feedback. Whether you need help with integration, want to share your experiences, or suggest improvements, our team and community are here to support you.
[Click here to join](https://join.slack.com/t/instantlyhub/shared_invite/zt-33fccx5j4-iURKIfEvyLfioTIWSRb9PA).
# API v1 to v2 migration
Source: https://developer.instantly.ai/guides/api-v1-migration
Endpoint mapping and migration guide for moving from API v1 to API v2.
# API v1 to API v2 migration
API v1 was deprecated on **January 19, 2026**. Use API v2 for all new integrations.
The first version of the API is available [here](https://app.theneo.io/instantly-ai/instantlyapidocs/introduction).
API v2 comes with significantly more endpoints than v1, offering expanded functionality for managing your campaigns, leads, and accounts. This guide covers the migration paths for existing v1 endpoints.
## Integrations using API v1
**Integrations using API v1, like Zapier, Make, etc., will keep working without any disruptions.**
## API v2 API key
Get an API v2 key by following the [getting started guide](/getting-started/getting-started).
## API v1 to API v2 endpoint mapping
### Campaign endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| ------------------------------- | -------------------------------------- | ------ | ------------------------------------------------------------- |
| `GET /campaign/list` | `GET /api/v2/campaigns` | GET | Now supports pagination with `starting_after` |
| `GET /campaign/get/name` | `GET /api/v2/campaigns/{id}` | GET | Campaign name is in the response object |
| `GET /campaign/get/status` | `GET /api/v2/campaigns/{id}` | GET | Status is in the response object |
| `POST /campaign/set/name` | `PATCH /api/v2/campaigns/{id}` | PATCH | Use PATCH with `{"name": "New Name"}` |
| `GET /campaign/get/accounts` | `GET /api/v2/campaigns/{id}` | GET | Accounts are in the response object in the `email_list` array |
| `POST /campaign/set/accounts` | `PATCH /api/v2/campaigns/{id}` | PATCH | Update with `email_list` array |
| `POST /campaign/add-account` | `PATCH /api/v2/campaigns/{id}` | PATCH | Add to accounts array |
| `POST /campaign/remove-account` | `PATCH /api/v2/campaigns/{id}` | PATCH | Remove from accounts array |
| `POST /campaign/set/schedule` | `PATCH /api/v2/campaigns/{id}` | PATCH | Update `campaign_schedule` object |
| `POST /campaign/launch` | `POST /api/v2/campaigns/{id}/activate` | POST | Dedicated activate endpoint |
| `POST /campaign/pause` | `POST /api/v2/campaigns/{id}/pause` | POST | Dedicated pause endpoint |
### Analytics endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| --------------------------------- | ------------------------------------------ | ------ | ------------------------------------ |
| `GET /analytics/campaign/summary` | `GET /api/v2/campaigns/analytics` | GET | Pass campaign ID as query param `id` |
| `GET /analytics/campaign/count` | `GET /api/v2/campaigns/analytics/overview` | GET | Overview endpoint |
### Lead endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| ---------------------------- | --------------------------- | ------ | --------------------------------------- |
| `POST /lead/add` | `POST /api/v2/leads` | POST | Can add to campaign or lead list |
| `GET /lead/get` | `POST /api/v2/leads/list` | POST | Now POST for complex filtering |
| `POST /lead/delete` | `DELETE /api/v2/leads/{id}` | DELETE | Delete by lead ID |
| `POST /lead/update-status` | `PATCH /api/v2/leads/{id}` | PATCH | Update `interest_status` field |
| `POST /lead/variable/update` | `PATCH /api/v2/leads/{id}` | PATCH | Update `payload` object |
| `POST /lead/variable/set` | `PATCH /api/v2/leads/{id}` | PATCH | Set fields in `payload` object |
| `POST /lead/variable/delete` | `PATCH /api/v2/leads/{id}` | PATCH | Update `payload` without deleted fields |
### Account endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| ----------------------------- | -------------------------------------- | ------ | ----------------------------------------- |
| `GET /account/list` | `GET /api/v2/accounts` | GET | Supports filtering and limiting |
| `POST /account/check-vitals` | `POST /api/v2/accounts/test/vitals` | POST | Same behavior |
| `GET /account/get/status` | `GET /api/v2/accounts/{email}` | GET | Get by email address |
| `POST /account/warmup/enable` | `POST /api/v2/accounts/warmup/enable` | POST | Returns background job |
| `POST /account/warmup/pause` | `POST /api/v2/accounts/warmup/disable` | POST | Note: endpoint is `/disable` not `/pause` |
| `POST /account/delete` | `DELETE /api/v2/accounts/{email}` | DELETE | Delete by email |
### Blocklist endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| ------------------------ | ----------------------------------------- | ------ | ------------------ |
| `POST /blocklist/add` | `POST /api/v2/block-lists-entries` | POST | Add entries |
| `POST /blocklist/remove` | `DELETE /api/v2/block-lists-entries/{id}` | DELETE | Delete by entry ID |
### Unibox (email) endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| --------------------------------- | ------------------------------------------------------ | ------ | ------------------------------------------ |
| `GET /unibox/emails/list` | `GET /api/v2/emails` | GET | List with filtering |
| `GET /unibox/emails/unread/count` | `GET /api/v2/emails/unread/count` | GET | Dedicated count endpoint |
| `POST /unibox/threads/mark-read` | `POST /api/v2/emails/threads/{thread_id}/mark-as-read` | PATCH | Mark emails as read by updating the status |
| `POST /unibox/reply` | `POST /api/v2/emails/reply` | POST | Reply with `reply_to_uuid` in body |
### Tags endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| -------------------- | ------------------------------------------ | ------ | -------------------- |
| `POST /tag/create` | `POST /api/v2/custom-tags` | POST | Create tag |
| `GET /tag/get` | `GET /api/v2/custom-tags/{id}` | GET | Get by ID |
| `GET /tag/list` | `GET /api/v2/custom-tags` | GET | List all |
| `PATCH /tag/update` | `PATCH /api/v2/custom-tags/{id}` | PATCH | Update by ID |
| `DELETE /tag/delete` | `DELETE /api/v2/custom-tags/{id}` | DELETE | Delete by ID |
| `POST /tag/assign` | `POST /api/v2/custom-tags/toggle-resource` | POST | Assign/unassign tags |
### Email verification endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| -------------------------- | ---------------------------------------- | ------ | --------------------------- |
| `POST /verify/email` | `POST /api/v2/email-verification` | POST | Verify single email |
| `GET /verify/email/result` | `GET /api/v2/email-verification/{email}` | GET | Get result by email address |
### Custom tracking domain endpoints
| API v1 endpoint | API v2 endpoint | Method | Notes |
| ----------------------------- | --------------------------------- | ------ | --------------------------------- |
| `GET /tracking-domain/status` | `GET /api/v2/accounts/ctd-status` | GET | Get custom tracking domain status |
# OAuth connection flow
Source: https://developer.instantly.ai/guides/oauth-connection-flow
Programmatically connect Google and Microsoft OAuth accounts to your Instantly workspace.
# OAuth account API integration guide
This API allows third-party developers to programmatically connect Google and Microsoft OAuth accounts to Instantly workspaces without requiring browser automation through the frontend.
## Flow summary
1. Send an API request to get the OAuth URL.
* Send this request with the API key of the workspace to which you want to connect the account.
2. Open that URL in a new browser tab and connect the account.
* The account will automatically connect behind the scenes.
* There is no need for any Instantly login cookie, or to open the Instantly dashboard at all.
* Optionally, you can check status using the session ID you receive from step 1.
## Authentication
All API requests require authentication using your Instantly API key:
```bash theme={null}
Authorization: Bearer
```
The API key must have the `accounts:create` scope for initializing OAuth and the `accounts:read` scope for checking status.
## Provider-specific notes
The API endpoints and flow are identical -- simply replace the provider name in the init endpoint:
| Provider | Init endpoint | Status endpoint (same for both) |
| ------------- | ----------------------------------- | --------------------------------------------- |
| **Google** | `POST /api/v2/oauth/google/init` | `GET /api/v2/oauth/session/status/:sessionId` |
| **Microsoft** | `POST /api/v2/oauth/microsoft/init` | `GET /api/v2/oauth/session/status/:sessionId` |
**Google**
* Only Google Workspace (GSuite) accounts are supported.
* Personal Gmail accounts (`@gmail.com`) will be rejected.
**Microsoft**
* Supports both Microsoft 365 (business) and personal Microsoft accounts.
* Uses Outlook / Office 365 for email access.
All code examples below use Google endpoints. To use Microsoft instead, replace `google` with `microsoft` in all URLs.
## API endpoints
### 1. Initialize OAuth session
Creates a new OAuth session and returns the Google authorization URL.
**Endpoint:** `POST /api/v2/oauth/google/init`
This endpoint has special rate limits to comply with upstream provider limits. See [Rate limits](#rate-limits) for details.
**Request:**
```bash theme={null}
curl -X POST "https://api.instantly.ai/api/v2/oauth/google/init" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
```
**Response:**
```json theme={null}
{
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"auth_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&state=api_session:550e8400-e29b-41d4-a716-446655440000&...",
"expires_at": "2024-01-15T10:30:00.000Z"
}
```
| Field | Type | Description |
| ------------ | ----------------- | ----------------------------------------------- |
| `session_id` | string | Unique session ID for polling status |
| `auth_url` | string | Google authorization URL to open in the browser |
| `expires_at` | string (ISO 8601) | Session expiry time (10 minutes from creation) |
### 2. Check OAuth status
Poll this endpoint to check the result of the OAuth flow.
**Endpoint:** `GET /api/v2/oauth/session/status/:sessionId`
**Request:**
```bash theme={null}
curl "https://api.instantly.ai/api/v2/oauth/session/status/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response (pending):**
```json theme={null}
{
"status": "pending"
}
```
**Response (success):**
```json theme={null}
{
"status": "success",
"email": "user@example.com",
"name": "John Doe",
"account_id": "user@example.com"
}
```
**Response (error):**
```json theme={null}
{
"status": "error",
"error": "account_exists",
"error_description": "Account already exists in another workspace"
}
```
**Response (expired):**
```json theme={null}
{
"status": "expired"
}
```
| Status | Description |
| --------- | ----------------------------------- |
| `pending` | User has not completed OAuth yet |
| `success` | Account successfully connected |
| `error` | OAuth failed (see error fields) |
| `expired` | Session expired (10-minute timeout) |
## Integration guide
### Step 1: Initialize the OAuth session
Call the init endpoint to get a session ID and authorization URL.
```javascript theme={null}
const response = await fetch('https://api.instantly.ai/api/v2/oauth/google/init', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
});
const { session_id, auth_url, expires_at } = await response.json();
```
### Step 2: Open the authorization URL
Direct the user to the `auth_url` to complete Google authentication. You can do this by:
* **Option A:** Opening in a new browser tab/window
* **Option B:** Opening in a popup window
* **Option C:** Redirecting the current page (requires handling the return)
```javascript theme={null}
// Option A: New tab
window.open(auth_url, '_blank');
// Option B: Popup window
const popup = window.open(
auth_url,
'google-oauth',
'width=500,height=600,scrollbars=yes'
);
```
### Step 3: Poll for completion
Poll the status endpoint until the session completes or expires.
```javascript theme={null}
async function pollOAuthStatus(sessionId, apiKey, maxAttempts = 60) {
for (let attempt = 0; attempt < maxAttempts; attempt++) {
const response = await fetch(
`https://api.instantly.ai/api/v2/oauth/session/status/${sessionId}`,
{
headers: { 'Authorization': `Bearer ${apiKey}` }
}
);
const result = await response.json();
if (result.status === 'success') {
return { success: true, account: result };
}
if (result.status === 'error') {
return { success: false, error: result.error, description: result.error_description };
}
if (result.status === 'expired') {
return { success: false, error: 'expired', description: 'Session expired' };
}
// Still pending, wait before next poll
await new Promise(resolve => setTimeout(resolve, 2000)); // 2 second interval
}
return { success: false, error: 'timeout', description: 'Polling timeout exceeded' };
}
// Usage
const result = await pollOAuthStatus(session_id, API_KEY);
if (result.success) {
console.log(`Account connected: ${result.account.email}`);
} else {
console.error(`OAuth failed: ${result.description}`);
}
```
## Complete examples
### Node.js
```javascript theme={null}
const fetch = require('node-fetch');
const API_KEY = 'your-api-key';
const API_BASE = 'https://api.instantly.ai/api/v2';
async function connectGoogleAccount() {
// Step 1: Initialize OAuth session
console.log('Initializing OAuth session...');
const initResponse = await fetch(`${API_BASE}/oauth/google/init`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
});
const { session_id, auth_url, expires_at } = await initResponse.json();
console.log(`Session created: ${session_id}`);
console.log(`Expires at: ${expires_at}`);
console.log(`\nPlease open this URL in your browser to authenticate:\n${auth_url}\n`);
// Step 2: Poll for completion
console.log('Waiting for authentication...');
const pollInterval = 2000; // 2 seconds
const maxWaitTime = 10 * 60 * 1000; // 10 minutes
const startTime = Date.now();
while (Date.now() - startTime < maxWaitTime) {
const statusResponse = await fetch(
`${API_BASE}/oauth/session/status/${session_id}`,
{
headers: { 'Authorization': `Bearer ${API_KEY}` }
}
);
const result = await statusResponse.json();
switch (result.status) {
case 'success':
console.log('\nAccount connected successfully!');
console.log(` Email: ${result.email}`);
console.log(` Name: ${result.name}`);
console.log(` Account ID: ${result.account_id}`);
return result;
case 'error':
console.error(`\nOAuth failed: ${result.error}`);
console.error(` ${result.error_description}`);
throw new Error(result.error_description);
case 'expired':
console.error('\nSession expired');
throw new Error('OAuth session expired');
case 'pending':
process.stdout.write('.');
break;
}
await new Promise(resolve => setTimeout(resolve, pollInterval));
}
throw new Error('Polling timeout exceeded');
}
// Run
connectGoogleAccount()
.then(() => process.exit(0))
.catch(err => {
console.error(err.message);
process.exit(1);
});
```
### Python
```python theme={null}
import requests
import time
API_KEY = 'your-api-key'
API_BASE = 'https://api.instantly.ai/api/v2'
def connect_google_account():
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json'
}
# Step 1: Initialize OAuth session
print('Initializing OAuth session...')
init_response = requests.post(
f'{API_BASE}/oauth/google/init',
headers=headers
)
init_data = init_response.json()
session_id = init_data['session_id']
auth_url = init_data['auth_url']
expires_at = init_data['expires_at']
print(f'Session created: {session_id}')
print(f'Expires at: {expires_at}')
print(f'\nPlease open this URL in your browser to authenticate:\n{auth_url}\n')
# Step 2: Poll for completion
print('Waiting for authentication...', end='', flush=True)
poll_interval = 2 # seconds
max_attempts = 300 # 10 minutes at 2 second intervals
for _ in range(max_attempts):
status_response = requests.get(
f'{API_BASE}/oauth/session/status/{session_id}',
headers=headers
)
result = status_response.json()
if result['status'] == 'success':
print('\n\nAccount connected successfully!')
print(f" Email: {result['email']}")
print(f" Name: {result['name']}")
print(f" Account ID: {result['account_id']}")
return result
elif result['status'] == 'error':
print(f"\n\nOAuth failed: {result['error']}")
print(f" {result.get('error_description', '')}")
raise Exception(result.get('error_description', result['error']))
elif result['status'] == 'expired':
print('\n\nSession expired')
raise Exception('OAuth session expired')
print('.', end='', flush=True)
time.sleep(poll_interval)
raise Exception('Polling timeout exceeded')
if __name__ == '__main__':
connect_google_account()
```
## Error handling
### Common errors
| Error code | Description | Resolution |
| ---------------- | ---------------------------------------------- | -------------------------------------------------------------------------- |
| `account_exists` | Account already connected to another workspace | The Google account is already connected to a different Instantly workspace |
| `server_error` | Internal server error | Retry the OAuth flow |
| `expired` | Session expired | Start a new OAuth flow (sessions expire after 10 minutes) |
### HTTP status codes
| Code | Endpoint | Description |
| ----- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | All | Success |
| `401` | All | Unauthorized -- invalid or missing API key |
| `404` | Status | Session not found or belongs to a different workspace |
| `429` | All | Rate limit exceeded — init endpoints have [additional stricter limits](#rate-limits); all endpoints share the [standard API rate limit](/getting-started/rate-limit) |
| `503` | Init only | Upstream provider temporarily unavailable — retry after a short delay |
## Security considerations
1. **Session binding:** Sessions are tied to the workspace that created them. Only the same API key/workspace can poll for status.
2. **One-time use:** Successful or error sessions are deleted after the first status retrieval.
3. **Short TTL:** Sessions expire after 10 minutes if not completed.
4. **No token exposure:** OAuth refresh tokens are never returned via the API -- they are stored directly in the database.
5. **GSuite only:** Only Google Workspace (GSuite) accounts are supported. Personal Gmail accounts will be rejected.
## Rate limits
The OAuth init endpoints (`/oauth/google/init` and `/oauth/microsoft/init`) have **stricter rate limits** than the [standard API rate limit](/getting-started/rate-limit). These exist to stay compliant with upstream provider (Google, Microsoft) rate limits on OAuth authorization requests.
* **Init endpoint (per workspace):** 75 requests per minute. Exceeding returns `429`.
* **Init endpoint (per IP):** 150 requests per minute. Exceeding returns `429`.
* **Escalating IP blocks:** Persistent abuse from the same IP triggers progressively longer blocks (30 minutes → 2 hours → 24 hours).
When an IP is blocked, the `429` response includes a `Retry-After` header with the remaining block duration in seconds. Use this value to schedule your next retry.
* **Circuit breaker:** If the upstream provider (Google/Microsoft) is temporarily rate-limiting Instantly, init requests return `503 Service Unavailable`. This resolves automatically — retry after a short delay.
* **Provider isolation:** Rate limits, IP blocks, and circuit breakers are tracked per provider. A Microsoft outage does not affect Google init requests, and vice versa.
* **Status endpoint:** [Standard API rate limits](/getting-started/rate-limit) apply.
* **Recommended polling interval:** 5 seconds.
## Troubleshooting
### User sees "Non GSuite accounts are not allowed"
The OAuth flow only supports Google Workspace (GSuite) accounts. Personal Gmail accounts (`@gmail.com`) are not supported.
### Session expires before the user completes OAuth
Sessions have a 10-minute TTL. Ensure users complete the OAuth flow promptly. If needed, initialize a new session.
### Status returns 404 "Session not found"
This can happen if:
* The session ID is incorrect.
* The session was created by a different workspace/API key.
* The session has already been consumed (success/error status already retrieved).
### Account shows as connected but status returns "error"
Check the `error` and `error_description` fields. Common issues:
* Account already exists in another workspace.
* Account was blocked by admin.
* Account contains prohibited content.
# Webhook events
Source: https://developer.instantly.ai/guides/webhook-events
Schema reference and event types for Instantly webhook payloads.
# Webhook events
Webhook event payloads follow the schema below.
```json theme={null}
{
// Base fields (always present)
"timestamp": "string", // ISO timestamp when the event occurred
"event_type": "string", // Type of event (see event types below)
"workspace": "string", // UUID of the workspace
"campaign_id": "string", // UUID of the campaign
"campaign_name": "string", // Name of the campaign
// Optional fields
"lead_email": "string", // Email address of the lead (if the event is for a lead)
"email_account": "string", // Email account used to send the message (if applicable)
"unibox_url": "string", // URL to view the conversation in Unibox (only for reply events)
// Step information (if available)
"step": 1, // Step number in the campaign (starting at 1)
"variant": 1, // Variant number of the step (starting at 1)
"is_first": true, // Whether this is the first event of this type for the lead
// Email information (for sent emails)
"email_id": "string", // The ID of the email (reply_to_uuid). You can use it to reply via the reply endpoint.
"email_subject": "string",
"email_text": "string",
"email_html": "string",
// Reply information (for reply events)
"reply_text_snippet": "string", // Short preview of the reply content
"reply_subject": "string", // Subject of the reply email
"reply_text": "string", // Full plain-text content of the reply
"reply_html": "string" // Full HTML content of the reply
// Lead data (merged from database if available)
// Additional lead data fields from your database may appear as extra keys.
}
```
## Event types
### Email events
| Event type | Description |
| --------------------- | -------------------------------- |
| `email_sent` | An email was sent |
| `email_opened` | A lead opened an email |
| `reply_received` | A reply was received from a lead |
| `auto_reply_received` | An auto-reply was received |
| `link_clicked` | A lead clicked a tracked link |
| `email_bounced` | An email bounced |
| `lead_unsubscribed` | A lead unsubscribed |
| `account_error` | An account-level error occurred |
| `campaign_completed` | A campaign completed |
### Lead status events
| Event type | Description |
| --------------------- | ----------------------------- |
| `lead_neutral` | Lead marked as neutral |
| `lead_interested` | Lead marked as interested |
| `lead_not_interested` | Lead marked as not interested |
### Meeting events
| Event type | Description |
| ------------------------ | ----------------------- |
| `lead_meeting_booked` | A meeting was booked |
| `lead_meeting_completed` | A meeting was completed |
### Other lead events
| Event type | Description |
| -------------------- | --------------------------- |
| `lead_closed` | Lead marked as closed |
| `lead_out_of_office` | Lead is out of office |
| `lead_wrong_person` | Lead marked as wrong person |
### Custom labels
Any custom label configured in your workspace will be sent as the `event_type` value as-is.
# Workspace group
Source: https://developer.instantly.ai/guides/workspace-group
Manage multiple sub workspaces from a single admin workspace using the workspace group feature.
# Workspace group
A workspace group allows you to control multiple workspaces (**sub workspaces**) from within a single **admin workspace**.
Read on for more details about how this feature works.
## Using a single API key to manage sub workspaces
You can use a single API key to manage any of your sub workspaces. It works with **all** API endpoints. The API key must have the same scopes as it would when the endpoints are called normally.
### Call API endpoints "as" a specific sub workspace
You need to add an extra header to your requests called `x-as-workspace` and set its value to the workspace `id` of the sub workspace.
That is the only difference between a regular API call and a call on behalf of a sub workspace. If you do not provide the `x-as-workspace` header, requests will go through as usual.
## Limitations
There are a few limitations regarding this feature:
1. For privacy and security reasons, a workspace cannot be both an admin workspace and a sub workspace at the same time.
* If you own an admin workspace, it cannot be a sub workspace.
* If your workspace is managed by an admin workspace, it cannot be an admin workspace.
2. Only workspace **owners** and **admins** can invite workspaces to join their workspace group.
3. Only workspace **owners** and **admins** can remove sub workspaces from the admin workspace.
4. Only workspace **owners** can leave a workspace group.
## Adding sub workspaces
There are two ways to add sub workspaces -- from the app and using the API. For both methods, you will need the ID of the workspace you want to invite.
**Important: both methods send an invitation to the workspace owner. The workspace becomes a sub workspace only after the invitation is accepted.**
### Adding sub workspaces from the app
1. Go to the [Settings > Account](https://app.instantly.ai/app/settings/account) page.
2. Go to the **Workspace Group** tab.
3. Click the **Add sub workspace** button.
4. Paste the workspace ID into the text field.
5. Press the **Add sub workspace** button to send the invitation.
Once the invitation is accepted, the workspace will become a sub workspace.
### Adding sub workspaces using the API
1. Use the `POST /workspace-group-members` endpoint.
2. Set the `sub_workspace_id` field to the workspace ID you want to invite.
3. Send the request.
Once the invitation is accepted, the workspace will become a sub workspace.
## Removing sub workspaces
You can remove sub workspaces from the app or through the API.
### Removing sub workspaces from the app
1. Go to the [Settings > Account](https://app.instantly.ai/app/settings/account) page.
2. Go to the **Workspace Group** tab.
3. Find the sub workspace under the **Sub workspaces** section.
4. Click the **Remove** button.
5. The workspace will be removed immediately.
### Removing sub workspaces using the API
1. Use the `GET /workspace-group-members` endpoint to fetch a list of sub workspaces for your current workspace.
2. Identify the item where `sub_workspace_id` matches the workspace ID you want to remove.
3. Send a request to `DELETE /workspace-group-members/:id`, replacing `:id` with the `id` field of the workspace group member from the previous step. Note: the `id` is the workspace group member ID, not the workspace ID.
4. The workspace will be removed immediately.
## Leaving a workspace group
As a sub workspace, you can always leave the workspace group. You can do it either through the app or through the API.
**Remember: only workspace owners can leave workspace groups.**
### Leaving a workspace group through the app
1. Go to the [Settings > Account](https://app.instantly.ai/app/settings/account) page.
2. Go to the **Workspace Group** tab.
3. Press the **Leave workspace group** button under the **Admin workspace** section.
4. Your workspace will immediately leave the workspace group.
### Leaving a workspace group through the API
1. Call the `GET /workspace-group-members/admin` endpoint.
2. Get the `workspace_group_member_id` field (this is the `id` field of the `workspace_group_member`).
3. Send a request to `DELETE /workspace-group-members/:id`, replacing `:id` with the `workspace_group_member_id` from the previous request.
4. Your workspace will immediately leave the workspace group.