API Explorer (2.0.0)

The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the ApiKeyAuth_token blue text.

Servers

Instantly API Server

https://api.instantly.ai/

Mock server

https://developer.instantly.ai/_mock/api/v2/

Analytics

Endpoints related to analytics

Operations

OAuth

OAuth authentication endpoints for connecting Google and Microsoft email accounts

Operations

Account

An email account that can be used to send campaigns

Operations

Campaign

A campaign that can be sent to a list of recipients

Operations

Email

A campaign email, a reply, a manually sent email, or any other email that's visible in the Unibox

Operations

Email Verification

A single email verification

Operations

Lead List

A list used to store leads

Operations

Inbox Placement Test

An inbox placement test

Operations

Inbox Placement Analytics

Analytics data for individual emails in inbox placement tests

Operations

Inbox Placement Blacklist & SpamAssassin Report

Report data for an inbox placement test

Operations

API Key

Operations

Account Campaign Mapping

Operations

Lead

A lead entity representing an individual lead

Operations

Background Job

A background job that can be used to perform long-running tasks

Operations

Custom Tag

A custom tag for organizing and categorizing accounts and campaigns. You can use them as filters in apis that list accounts and campaigns.

Operations

Custom Tag Mapping

This entity represents a tag being assigned to a specific campaign or email account. When an email account is assigned a tag, a new custom tag mapping entry is created, which connects the tag (tag_id field) with the email account (resource_id field). You can use it to see which tag si connected to which resource.

Operations

Block List Entry

A blocked email or domain

Operations

Lead Label

A custom label for categorizing and managing leads

Operations

Workspace

A workspace entity representing a workspace

Operations

SuperSearch Enrichment

An enrichment can take different forms, such as email enrichment or LinkedIn enrichment. Leads may be imported from SuperSearch using the dedicated endpoint, or enriched directly within a list or campaign by attaching an enrichment to it.

Operations

Workspace Group Member

A member of a workspace group. You can use the endpoints within this entity to manage the members of a workspace group.

Operations

Workspace Member

A member of a workspace with associated user details

Operations

Campaign Subsequence

A subsequence entity representing a follow-up sequence

Operations

Audit Log

Audit log records for tracking system activities

Operations

Webhook

A webhook subscription for receiving event notifications

Operations

Webhook Event

A webhook event that was sent or attempted to be sent

Operations

DFY Email Account Order

A Done-For-You email account order

Operations

DFY Email Account Order

A Done-For-You email account order

workspace_idstringread-onlyrequired

ID of the workspace associated with the email account order

Example: "workspace_12345"

domainstringread-onlyrequired

Domain of the email account

Example: "example.com"

timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the order was created

Example: "2026-02-24T17:33:20.673Z"

forwarding_domainnull or string

Forwarding domain for the email account, if any

Example: "forward.example.com"

is_pre_warmed_upnull or boolean

Indicates if the account is pre-warmed up

Example: true

timestamp_cancellednull or string(date-time)read-only

Timestamp when the order was cancelled, if applicable

Example: "2026-02-24T17:33:20.673Z"

{
  "workspace_id": "workspace_12345",
  "domain": "example.com",
  "forwarding_domain": "forward.example.com",
  "is_pre_warmed_up": true,
  "timestamp_cancelled": "2026-02-24T17:33:20.673Z",
  "timestamp_created": "2026-02-24T17:33:20.673Z"
}

Place a DFY email account order

Request

This endpoint allows you to place an order for Done-For-You (DFY) email accounts with your own custom domains.
You can order up to 5 email accounts per domain.
This endpoint can place a DFY order, a pre-warmed up order, or an order to buy extra accounts to already ordered domains (please check the order_type field for more information).
We support the following domain extensions (tlds): .com, .org.
You can check the availability of your desired domain using the /dfy-email-account-orders/domains/check endpoint before placing an order.
If you choose to buy pre-warmed up accounts, please use the /dfy-email-account-orders/domains/pre-warmed-up-list endpoint to see a list of available pre-warmed up domains first.
If no pre-warmed up domains are available, then you can't place your order, but you can still buy regular DFY accounts.
Please make sure your workspace has an Outreach plan to use this endpoint.

Requires one of the following scopes: dfy_email_account_orders:create, dfy_email_account_orders:all, all:create, all:all

Bodyapplication/jsonrequired

itemsArray of objectsrequired

List of domains and accounts to order

items[].domainstringrequired

The domain to use for the email accounts.For regular DFY accounts the only allowed domain extensions (tlds) are .com and .org.For regular DFY accounts - you can check the domain availability using the /dfy-email-account-orders/domains/check endpoint before placing an order.For pre-warmed up domains - use the /dfy-email-account-orders/domains endpoint to get a list of available domains.

Example: "example.com"

items[].email_providernumber

The email provider to use for the email accounts. For now you can order only Google accounts, and this parameter can have only one value.

Default 1

Value	Description
1	Google

Example: 1

items[].forwarding_domainstring

An optional domain to forward emails to. This domain must be different from the main domain.

Example: "forward-to-this-domain.com"

items[].accountsArray of objects<= 5 items

List of email accounts to create (only if pre_warmed_up field is false). For pre-warmed up domains this field will be ignored because the accounts are already created and can't be changed. Please provide minimum 1 and maximum 5 accounts per domain.

Default []

order_typestringrequired

The type of order to place. Please check the docs because this endpoint performs different actions based on the order type.

Enum Value	Description
dfy	Regular DFY accounts - it will place an order to buy new DFY accounts
pre_warmed_up	Pre-warmed up accounts - it will place an order to buy new pre-warmed up accounts
extra_accounts	Extra accounts - it will place an order to add extra accounts to already ordered domains

Example: "dfy"

simulationboolean

Whether to run a simulation of the order ot not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).

Default false

Example: false

curl -i -X POST \
  https://api.instantly.ai/api/v2/dfy-email-account-orders \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "items": [
      {
        "domain": "example.com"
      }
    ],
    "order_type": "dfy"
  }'

Responses

Default Response

Bodyapplication/json

order_placedbooleanrequired

Whether the order was placed or not. If true, then the order was placed successfully. If false, then the order was not placed due to an error or simulation mode was enabled.

Example: true

order_is_validbooleanrequired

Whether the order is valid or not. If true, then the order is valid and can be placed. If false, then the order is not valid and cannot be placed. Use this field when you run a simulation to understand whether a real order would be valid.

Example: true

unavailable_domainsArray of stringsrequired

The list of unavailable domains (if any)

Example: ["example.com"]

blacklist_domainsArray of stringsrequired

The list of blacklisted domains (if any)

Example: ["example.com","acme.com"]

invalid_domainsArray of stringsrequired

The list of invalid domains (if any)

Example: ["example.com","acme.com"]

invalid_forwarding_domainsArray of stringsrequired

The list of invalid forwarding domains (if any)

Example: ["example.com","acme.com"]

invalid_accountsArray of objectsrequired

The list of invalid accounts (if any)

invalid_accounts[].domainstringrequired

The domain

Example: "example.com"

invalid_accounts[].first_namestringrequired

The account first name

Example: "John"

invalid_accounts[].last_namestringrequired

The account last name

Example: "Doe"

invalid_accounts[].emailstringrequired

The account email

Example: "john.doe@example.com"

invalid_accounts[].reasonstringrequired

The reason why the account is invalid

Example: "First name is required"

missing_domain_ordersArray of stringsrequired

The list of domains that are missing order (if any). Can happen when you order extra accounts for domains that you didn't order before.

Example: ["example.com"]

domains_without_accountsArray of stringsrequired

The list of domains without accounts (if any). The accounts field for items in the items array for these domains was empty.

Example: ["example.com","acme.com"]

free_domainsArray of stringsrequired

The list of domains that are free (domains can be free during promotions)

Example: ["example.com","acme.com"]

number_of_domains_orderednumberrequired

The number of domains ordered

Example: 1

number_of_accounts_orderednumberrequired

The number of accounts ordered

Example: 1

price_per_account_per_monthnumberrequired

The price per account per month

Example: 10

price_per_domain_per_yearnumberrequired

The price per domain per year

Example: 100

total_domains_price_per_yearnumberrequired

The total price per domain per year

Example: 100

total_accounts_price_per_monthnumberrequired

The total price per account per month

Example: 10

total_price_per_monthnumberrequired

The total price per month you will have to pay for the order

Example: 100

total_price_per_yearnumberrequired

The total price per year you will have to pay for the order

Example: 100

total_pricenumberrequired

The total price you will have to pay for the order at the moment. This is the sum of the total_accounts_price_per_month and the total_domains_price_per_year fields.

Example: 100

total_discountnumberrequired

The total discount you will get for the order at the moment. Discounts are applied automatically when we're running promotions.

Example: 100

simulationbooleanrequired

Whether to run the request in simulation mode or not. If set to true, the order will NOT be placed, your card will NOT be charged, and only a price quote will be returned. We will still check the validity of the order and the accounts, and return the results of the validation (if the order_is_valid field is true, then the order would be valid and could be placed).

Example: true

order_itemsArray of objectsrequired

The list of items that were ordered, with the pricing information for each item.

order_items[].domainstringrequired

The domain to use for the email accounts.

Example: "example.com"

order_items[].accountsArray of objectsrequired

The list of accounts that were ordered for the domain.

order_items[].accounts[].email_address_prefixstringrequired

The email address prefix of the account.

Example: "john.doe"

order_items[].accounts[].first_namestringrequired

The account first name.

Example: "John"

order_items[].accounts[].last_namestringrequired

The account last name.

Example: "Doe"

order_items[].email_providernumberrequired

The email provider to use for the domain.

Example: 1

order_items[].domain_pricenumberrequired

The price for the domain.

Example: 100

order_items[].accounts_pricenumberrequired

The total price for the accounts.

Example: 100

order_items[].total_pricenumberrequired

The total price for the item.

Example: 100

order_items[].total_discountnumberrequired

The total discount for the item.

Example: 100

order_items[].forwarding_domainstring

The forwarding domain to use for the domain.

Example: "example.com"

payment_method_last_4_digitsstringrequired

The last 4 digits of the payment method used for the order

Example: "1234"

payment_method_brandstringrequired

The brand of the payment method used for the order

Example: "Visa"

payment_method_name_on_cardstringrequired

The name on the card used for the order

Example: "John Doe"

order_errorstring

The error that occurred if the order was not placed. If the order was placed successfully, then this field will be omitted.

Enum Value	Description
unavailable_domains	Some domains are not available for order - check the `unavailable_domains` field
blacklist_domains	Some domains are blacklisted - check the `blacklist_domains` field
invalid_domains	Some domains are invalid - check the `invalid_domains` field
invalid_forwarding_domains	Some forwarding domains are invalid - check the `invalid_forwarding_domains` field
invalid_accounts	Some accounts are invalid - check the `invalid_accounts` field the list of invalid accounts
payment_failed	The payment failed - please make sure you have enough funds in your payment method
missing_domain_orders	Some domains are missing orders (when you set the `order_type` to `extra_accounts`, all the domains you want to add extra accounts to must be already ordered) - check the `missing_domain_orders` field
domains_without_accounts	Some domains are missing accounts - check the `domains_without_accounts` field

Example: "unavailable_domains"

Response

application/json

{
  "order_placed": true,
  "order_is_valid": true,
  "order_error": "unavailable_domains",
  "unavailable_domains": [
    "example.com"
  ],
  "blacklist_domains": [
    "example.com",
    "acme.com"
  ],
  "invalid_domains": [
    "example.com",
    "acme.com"
  ],
  "invalid_forwarding_domains": [
    "example.com",
    "acme.com"
  ],
  "missing_domain_orders": [
    "example.com"
  ],
  "domains_without_accounts": [
    "example.com",
    "acme.com"
  ],
  "invalid_accounts": [
    { … }
  ],
  "free_domains": [
    "example.com",
    "acme.com"
  ],
  "number_of_domains_ordered": 1,
  "number_of_accounts_ordered": 1,
  "price_per_account_per_month": 10,
  "price_per_domain_per_year": 100,
  "total_domains_price_per_year": 100,
  "total_accounts_price_per_month": 10,
  "total_price_per_month": 100,
  "total_price_per_year": 100,
  "total_price": 100,
  "total_discount": 100,
  "payment_method_last_4_digits": "1234",
  "payment_method_brand": "Visa",
  "payment_method_name_on_card": "John Doe",
  "simulation": true,
  "order_items": [
    { … }
  ]
}

List dfy email account order

Request

Requires one of the following scopes: dfy_email_account_orders:read, dfy_email_account_orders:all, all:read, all:all

Query

limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10

starting_afterstring

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: starting_after=01956fbd-0eb1-72db-a565-82977a586084

curl -i -X GET \
  'https://api.instantly.ai/api/v2/dfy-email-account-orders?limit=10&starting_after=01956fbd-0eb1-72db-a565-82977a586084' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of DFY Email Account Order

Bodyapplication/json

itemsArray of objects(DFY Email Account Order)required

The list of DFY Email Account Order

items[].workspace_idstringread-onlyrequired

ID of the workspace associated with the email account order

Example: "workspace_12345"

items[].domainstringread-onlyrequired

Domain of the email account

Example: "example.com"

items[].timestamp_createdstring(date-time)read-onlyrequired

Timestamp when the order was created

Example: "2026-02-24T17:33:20.673Z"

items[].forwarding_domainnull or string

Forwarding domain for the email account, if any

Example: "forward.example.com"

items[].is_pre_warmed_upnull or boolean

Indicates if the account is pre-warmed up

Example: true

items[].timestamp_cancellednull or string(date-time)read-only

Timestamp when the order was cancelled, if applicable

Example: "2026-02-24T17:33:20.673Z"

next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API

Example: "019c90b6-927a-7d11-b4cc-d1b683ca536d"

Response

application/json

{
  "items": [
    { … }
  ],
  "next_starting_after": "019c90b6-927a-7d11-b4cc-d1b683ca536d"
}

Generate similar available domains

Request

This endpoint will generate a list of similar AND available domains based on the provided domain.. It will return a maximum number of 66 suggestions per extension (tld) requested.. All the returned domains will be available for order.

Requires one of the following scopes: dfy_email_account_orders:create, dfy_email_account_orders:all, all:create, all:all

Bodyapplication/jsonrequired

domainstringrequired

The domain to base the suggestions on

Example: "example.com"

tldsArray of strings

The extensions (tlds) to use for generating similar domains. By default, we will use com and org.

Default ["com","org"]

Items Enum Value	Description
com	.com domain
org	.org domain

Example: ["com"]

curl -i -X POST \
  https://api.instantly.ai/api/v2/dfy-email-account-orders/domains/similar \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "example.com"
  }'

Responses

Default Response

Bodyapplication/json

domainsArray of strings

List of similar and available domains

Example: ["acme.com"]

Response

application/json

{
  "domains": [
    "acme.com"
  ]
}

Check domains availability

Request

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.

. 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

Bodyapplication/jsonrequired

domainsArray of strings<= 50 itemsrequired

List of domains to check

Example: ["example.com"]

curl -i -X POST \
  https://api.instantly.ai/api/v2/dfy-email-account-orders/domains/check \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domains": [
      "example.com"
    ]
  }'

Responses

Default Response

Bodyapplication/json

resultsArray of objects

List of domains with their availability status

Response

application/json

{
  "results": [
    { … }
  ]
}

Get pre-warmed up domains

Request

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

Bodyapplication/json

This endpoint does not require any parameters in the request body.

extensionsArray of strings

A list of domain extensions to filter the results by. If not provided, all available extensions will be returned.

Default ["com","org","co"]

Items Enum Value	Description
com	.com domain
org	.org domain
co	.co domain

Example: ["com"]

searchstring

A search string to filter the domains by. This can be a partial or full domain name.

Example: "acme.com"

curl -i -X POST \
  https://api.instantly.ai/api/v2/dfy-email-account-orders/domains/pre-warmed-up-list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{}'

Responses

Default Response

Bodyapplication/json

domainsArray of strings

List of pre-warmed up domains available for order

Example: ["acme.com"]

Response

application/json

{
  "domains": [
    "acme.com"
  ]
}

List DFY ordered email accounts

Request

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

Query

limitinteger[ 1 .. 100 ]

The number of items to return

Example: limit=10

starting_afterstring

The ID of the last item in the previous page - used for pagination. You can use the value of the next_starting_after field from the previous response.

Example: starting_after=01956fbd-0eb1-72db-a565-82977a586084

with_passwordsboolean

Whether to include passwords in the response

Example: with_passwords=true

curl -i -X GET \
  'https://api.instantly.ai/api/v2/dfy-email-account-orders/accounts?limit=10&starting_after=01956fbd-0eb1-72db-a565-82977a586084&with_passwords=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of accounts

Bodyapplication/json

itemsArray of objectsrequired

The list of accounts

items[].idstringrequired

The unique identifier of the email account order

Example: "123e4567-e89b-12d3-a456-426614174000"

items[].domainstringrequired

The domain associated with the email account

Example: "example.com"

items[].emailstringrequired

The email address of the account

Example: "user@example.com"

items[].email_providernumberrequired

The email provider

Value	Description
1	Google

Example: 1

items[].first_namestringrequired

The first name of the account

Example: "John"

items[].last_namestringrequired

The last name of the account

Example: "Doe"

items[].is_pre_warmed_upbooleanrequired

Whether the account is pre-warmed up

Example: true

items[].timestamp_cancelledstringrequired

The timestamp when the account was cancelled

Example: "2025-01-01T00:00:00.000Z"

items[].timestamp_createdstringrequired

The timestamp when the account was created

Example: "2025-01-01T00:00:00.000Z"

items[].passwordstring

The password of the account (returned only if with_passwords is true). This field can be empty if the accounts are not ready yet.

Example: "password"

next_starting_afterstring

The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API

Example: "123e4567-e89b-12d3-a456-426614174000:2025-01-01T00:00:00.000Z"

Response

application/json

{
  "items": [
    { … }
  ],
  "next_starting_after": "123e4567-e89b-12d3-a456-426614174000:2025-01-01T00:00:00.000Z"
}

Cancel dfy email accounts

Request

This endpoint will cancel the DFY email accounts based on the provided email addresses.

Requires one of the following scopes: dfy_email_account_orders:delete, dfy_email_account_orders:all, all:delete, all:all

Bodyapplication/jsonrequired

accountsArray of stringsnon-emptyrequired

List of emails to cancel the DFY email accounts for.

Example: ["test@test.com"]

curl -i -X POST \
  https://api.instantly.ai/api/v2/dfy-email-account-orders/accounts/cancel \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "accounts": [
      "test@test.com"
    ]
  }'

Responses

Default Response

Bodyapplication/json

itemsArray of objectsrequired

The list of cancelled email accounts.

items[].idstringrequired

The unique identifier of the email account order

Example: "123e4567-e89b-12d3-a456-426614174000"

items[].domainstringrequired

The domain associated with the email account

Example: "example.com"

items[].emailstringrequired

The email address of the account

Example: "user@example.com"

items[].email_providernumberrequired

The email provider

Value	Description
1	Google

Example: 1

items[].first_namestringrequired

The first name of the account

Example: "John"

items[].last_namestringrequired

The last name of the account

Example: "Doe"

items[].is_pre_warmed_upbooleanrequired

Whether the account is pre-warmed up

Example: true

items[].timestamp_cancelledstringrequired

The timestamp when the account was cancelled

Example: "2025-01-01T00:00:00.000Z"

items[].timestamp_createdstringrequired

The timestamp when the account was created

Example: "2025-01-01T00:00:00.000Z"

Response

application/json

{
  "items": [
    { … }
  ]
}

Custom Prompt Template

Custom prompt templates for creating custom prompts

Sales Flow

Manages how sales users view and interact with campaign and lead lists within the sales flow.

Email Template

A campaign email template

Workspace Billing

Operations

CRM Actions

CRM related actions

Operations

API Explorer (2.0.0)

Analytics

OAuth

Account

Campaign

Email

Email Verification

Lead List

Inbox Placement Test

Inbox Placement Analytics

Inbox Placement Blacklist & SpamAssassin Report

API Key

Account Campaign Mapping

Lead

Background Job

Custom Tag

Custom Tag Mapping

Block List Entry

Lead Label

Workspace

SuperSearch Enrichment

Workspace Group Member

Workspace Member

Campaign Subsequence

Audit Log

Webhook

Webhook Event

DFY Email Account Order

DFY Email Account Order

Place a DFY email account order

RequestExpand all

Responses

Was this helpful?

List dfy email account order

Request

Responses

Was this helpful?

Generate similar available domains

Request

Responses

Was this helpful?

Check domains availability

Request

Responses

Was this helpful?

Get pre-warmed up domains

Request

Responses

Was this helpful?

List DFY ordered email accounts

Request

Responses

Was this helpful?

Cancel dfy email accounts

Request

Responses

Was this helpful?

Custom Prompt Template

Sales Flow

Email Template

Workspace Billing

CRM Actions

Schemas

Request