Instantly API Documentation

Welcome to Instantly. Let’s get started with getting you authenticated and ready to build! 🛠️

Finding your API key 🗝️

The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details.

Endpoints

GET

POST

GET

POST

The campaign endpoints allow you to interact with individual email campaigns, update their options, sending accounts, and status. See below for details.

Production:

https://api.instantly.ai/api

The lead endpoints allow you to interact with lead data in your workspace.

Endpoints

POST

GET

POST

The blocklist endpoints allow you to interact with your campaign blocklist. See below for details.

Endpoints

POST

The account endpoints allow you to interact with your sending accounts. See below for details.

Endpoints

GET

POST

GET

POST

Query Parameters

api_keystring Required

Your API Key

limitnumber

Number of results to return

skipnumber

Offset for pagination

Response

200

Object

Response Attributes

accountsarray

Show child attributes

curl --location 'https://api.instantly.ai/api/v1/account/list?api_key=API_KEY&limit=10&skip=5' \

{
  "accounts": [
    {
      "email": "email1@domain.com",
      "timestamp_created": "2022-03-29T09:50:30.526Z",
      "timestamp_updated": "2023-03-06T22:27:45.737Z",
      "payload": {
        "name": {
          "last": "Doe",
          "first": "Jane"
        },
        "warmup": {
          "limit": 20,
          "advanced": {
            "warm_ctd": false,
            "open_rate": 100,
            "random_range": {
              "max": 20,
              "min": 10
            },
            "weekday_only": false,
            "important_rate": 100,
            "read_emulation": false,
            "spam_save_rate": 100
          },
          "increment": 1,
          "reply_rate": 30
        },
        "imap_host": "imappro.zoho.eu",
        "imap_port": 993,
        "smtp_host": "smtppro.zoho.eu",
        "smtp_port": "465",
        "daily_limit": 50,
        "sending_gap": "0"
      }
    },
    {
      "email": "email2@domain.com",
      "timestamp_created": "2023-01-25T06:58:52.147Z",
      "timestamp_updated": "2023-03-09T01:46:49.684Z",
      "payload": {
        "name": {
          "last": "Doe",
          "first": "Jane"
        },
        "warmup": {
          "limit": 20,
          "advanced": {
            "warm_ctd": false,
            "open_rate": 100,
            "random_range": {
              "max": 20,
              "min": 10
            },
            "weekday_only": false,
            "important_rate": 100,
            "read_emulation": false,
            "spam_save_rate": 100
          },
          "increment": 1,
          "reply_rate": 30
        },
        "daily_limit": 50,
        "sending_gap": "0"
      }
    }
  ]
}

This endpoint allows you to quickly check if the MX, SPF, DKIM, and DMARC records have been properly set for a list of domains.

Body Parameters

api_keystring Required

Your API key

accountsarray

Show child attributes

Response

200

Object

Response Attributes

statusstring

Response status

success_listarray

Show child attributes

failure_listarray

Show child attributes

curl --location 'https://api.instantly.ai/api/v1/account/test/vitals' \
--data-raw '{
  "api_key": "",
  "accounts": [
    "test@instantly.ai",
    "me@broken941.com"
  ]
}'

{
  "status": "success",
  "success_list": [
    {
      "domain": "instantly.ai",
      "allPass": true,
      "mx": true,
      "spf": true,
      "dkim": "google",
      "dmarc": true
    }
  ],
  "failure_list": [
    {
      "domain": "broken941.com",
      "allPass": false,
      "mx": false,
      "spf": false,
      "dkim": false,
      "dmarc": false
    }
  ]
}

Query Parameters

api_keystring Required

Your API Key

emailstring Required

Response

200

Object

Response Attributes

accountstring

statusstring

warmup_statusstring

curl --location 'https://api.instantly.ai/api/v1/account/status?api_key=API_KEY&email=abc%40xyz.com' \

{
  "account": "abc@xyz.com",
  "status": "active",
  "warmup_status": "paused"
}

This API allows users to update the warmup status for a specific email address associated with their API key. By enabling warmup, users can ensure that the designated email address is prepared for receiving and processing incoming data effectively. This feature helps optimize the performance and reliability of email-related operations within the application.

Body Parameters

api_keystring Required

Your API key

emailstring Required

Email address to update warmup status for

Response

200

Object

Response Attributes

statusstring

The response status indicating the outcome of the warmup enable action

curl --location 'https://api.instantly.ai/api/v1/account/warmup/enable' \
--data-raw '{
  "api_key": "",
  "email": "abc@xyz.com"
}'

{
  "status": "success"
}

The "Pause warmup" section allows users to temporarily halt the warmup process for an account. By utilizing this functionality, users can manage the warmup status of their email addresses effectively. This feature provides control over the warmup process, allowing users to pause it as needed.

Body Parameters

api_keystring Required

Your API key

emailstring Required

Email address to update warmup status for

Response

200

Object

Response Attributes

statusstring

Indicates the status of the warmup pause operation

curl --location 'https://api.instantly.ai/api/v1/account/warmup/pause' \
--data-raw '{
  "api_key": "",
  "email": "abc@xyz.com"
}'

{
  "status": "success"
}

Body Parameters

api_keystring Required

Your API key

emailstring

(Optional) Email address to mark as fixed; set to false or skip this parameter to mark all accounts as fixed.

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/account/mark_fixed' \
--data-raw '{
  "api_key": "",
  "email": "abc@xyz.com"
}'

{
  "status": "success"
}

This API endpoint allows users to permanently remove an account from the system. By utilizing this functionality, users can securely delete unwanted accounts and associated data. This action is irreversible, ensuring that accounts are removed from the system effectively.

Body Parameters

api_keystring Required

Your API key

emailstring Required

Email address to update warmup status for

Response

200

Object

Response Attributes

statusstring

Status of the account deletion request

curl --location 'https://api.instantly.ai/api/v1/account/delete' \
--data-raw '{
  "api_key": "",
  "email": "abc@xyz.com"
}'

{
  "status": "success"
}

See the “Custom Tracking Domain” section for details on how to add, update, and remove custom tracking domains for sending accounts.

https://developer.instantly.ai/custom-tracking-domain

The account endpoints allow you to interact with the Instantly Unibox. See below for details.

Endpoints

GET

POST

The custom tag endpoints are a set of endpoints that allow you to manage custom tags and associate them with specific resources. Custom tags are labels or categories that you can assign to different entities, such as user accounts or campaigns, to organize and group them based on certain criteria.

Resource Type and Resource ID: The resource type and resource ID are used to uniquely identify a specific resource.

Resource Type: The resource type is a way to categorize different types of resources in your application. It helps distinguish between different entities that can have custom tags assigned to them. For example, you might have resource types such as "account" for user accounts and "campaign" for marketing campaigns.
Resource ID: The resource ID is a unique identifier for a specific resource within a resource type. It allows you to reference a particular resource when assigning or retrieving custom tags. For example, if you have a user account with an email address "johndoe@instantly.ai", the email address would be the resource ID for the "account" resource type.

Endpoints

POST

GET

PATCH

DELETE

POST

The Verification endpoints allow you to verify emails, including those behind catch-all domains.

See below for details.

There are currently two categories of verification endpoints.

Submitting a verification job
Checking the status of a verification job

Endpoints

POST

GET

The Custom Tracking Domain endpoints allow you to add, remove, or check status of custom tracking domains that are used for tracking campaign metrics such as opens, link clicks, etc.

Help article: https://help.instantly.ai/en/articles/6984188-custom-tracking-domain

Sections

Introduction

Finding your API key 🗝️

1

Go to Instantly Dashboard

2

Go to Settings → Integrations

3

Retrieve your API key

Campaign

Endpoints

GET

GET

GET

POST

GET

POST

POST

POST

POST

POST

POST

Analytics

Lead

Endpoints

POST

GET

POST

POST

POST

POST

POST

Blocklist

Endpoints

POST

POST

Account

What made this section unhelpful for you?

Endpoints

GET

POST

GET

POST

POST

POST

POST

What made this section unhelpful for you?

List accounts

Query Parameters

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Response

What made this section unhelpful for you?

Check account vitals

Body ParametersExpand all

ResponseExpand all

Response Attributes

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Node.js

Go

.NET

Response

What made this section unhelpful for you?

Get account status

Response

Body Parameters

Response