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 "List campaigns" section allows users to retrieve a list of campaigns associated with their account. Users can view details such as campaign IDs and names, enabling them to manage and track their marketing efforts effectively. Pagination options are available for handling large sets of campaign data.

Query Parameters

api_keystring Required

Your unique API key for authentication.

skipstring

Used for pagination

limitstring

Used for pagination (max 100)

Response

200

Object

Response Attributes

idstring

The unique identifier for each campaign.

namestring

The name of the campaign.

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

[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "My first campaign"
  },
  {
    "id": "935fb400-5bc9-44da-9c83-9ad169ec6701",
    "name": "My second campaign"
  }
]

The "Get campaign name" section allows users to retrieve the name of a specific campaign by providing the campaign ID. This feature is helpful for accessing campaign details and integrating them into external systems or applications. By utilizing this functionality, users can easily access and display campaign names without the need for manual input.

Query Parameters

api_keystring Required

A unique key provided to authorize access to the API and identify the user making the request.

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

Response

200

Object

Response Attributes

campaign_idstring

The unique identifier for the campaign, which can be obtained from the list endpoint or the campaign URL within the app.

campaign_namestring

The name of the campaign associated with the specified campaign_id.

curl --location 'https://api.instantly.ai/api/v1/campaign/get/name?api_key=API_KEY&campaign_id=00000000-0000-0000-0000-000000000000' \

{
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "campaign_name": "My first campaign"
}

This section allows users to retrieve the status of a specific campaign using its ID. By accessing this information, users can track the progress and performance of their campaigns without the need to navigate through multiple screens or interfaces. This feature streamlines the monitoring process and provides quick access to essential campaign status data.

Query Parameters

api_keystring Required

The API key used for authentication to access the campaign status information.

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

Response

200

Object

Response Attributes

campaign_idstring

The unique identifier for the campaign, which can be obtained from the list endpoint or from the campaign's URL within the app.

statusstring

The current status of the campaign, indicating its progress or state.

curl --location 'https://api.instantly.ai/api/v1/campaign/get/status?api_key=API_KEY&campaign_id=00000000-0000-0000-0000-000000000000' \

{
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "status": "active"
}

This section allows users to set a new name for their campaign. By providing the campaign ID and the desired name, users can easily update the name of their campaign. This feature simplifies the process of managing and organizing campaigns within the platform.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

namestring Required

The new name for your campaign

Response

200

Object

Response Attributes

statusstring

The response status of the operation.

curl --location 'https://api.instantly.ai/api/v1/campaign/set/name' \
--data '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "name": "New name"
}'

{
  "status": "success"
}

Get the list of sending accounts associated with a campaign

Query Parameters

api_keystring Required

Your API Key

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

Response

200

Object

Response Attributes

myemail@abc.comstring

Placeholder for the second response parameter.

second@xyz.comstring

Placeholder for the first response parameter.

curl --location 'https://api.instantly.ai/api/v1/campaign/get/accounts?api_key=API_KEY&campaign_id=00000000-0000-0000-0000-000000000000' \

[
  "myemail@abc.com",
  "second@xyz.com"
]

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

account_listarray

Show child attributes

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/campaign/set/accounts' \
--data-raw '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "account_list": [
    "123@xyz.com",
    "245@abc.com"
  ]
}'

{
  "status": "success"
}

This endpoint helps add a single sending account to the specified campaign.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

emailstring

Single email account to add

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/campaign/add/account' \
--data-raw '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "email": "me@email.com"
}'

{
  "status": "success"
}

This endpoint helps remove a single sending account from the specified campaign.

Body Parameters

api_keystring

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

emailstring

Single email account to remove

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/campaign/remove/account' \
--data-raw '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "email": "me@email.com"
}'

{
  "status": "success"
}

This endpoint helps you set one or more schedules for your campaign.

Body Parameters

api_keystring Required

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

start_datestring

Start date

end_datestring

End date - optional

schedulesarray

Show child attributes

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/campaign/set/schedules' \
--data '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000",
  "start_date": "2023-01-01",
  "end_date": "false",
  "schedules": [
    {
      "name": "Monday to Friday - 8am to 5pm Eastern",
      "days": {
        "1": true,
        "2": true,
        "3": true,
        "4": true,
        "5": true
      },
      "timezone": "America/Detroit",
      "timing": {
        "from": "08:00",
        "to": "17:00"
      }
    }
  ]
}'

{
  "status": "success"
}

The Launch campaign section allows users to initiate the launch of a campaign within the system. By providing the necessary parameters, such as the API key and campaign ID, users can trigger the campaign launch process seamlessly. The response will indicate the status of the launch operation, ensuring visibility and clarity on the campaign's progress.

Body Parameters

api_keystring

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

Response

200

Object

Response Attributes

statusstring

curl --location 'https://api.instantly.ai/api/v1/campaign/launch' \
--data '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000"
}'

{
  "status": "success"
}

The "Pause campaign" section allows users to temporarily halt a specific campaign within their account. By pausing a campaign, users can prevent it from being actively displayed or executed, providing control and flexibility in managing their marketing efforts. This functionality helps users optimize their campaigns by allowing them to make adjustments or assess performance before resuming activity.

Body Parameters

api_keystring Required

Your API key

campaign_idstring Required

Your campaign's id - you can get it from the list endpoint or the url when you have the campaign opened in the app.

Response

200

Object

Response Attributes

statusstring

The current status of the campaign.

curl --location 'https://api.instantly.ai/api/v1/campaign/pause' \
--data '{
  "api_key": "",
  "campaign_id": "00000000-0000-0000-0000-000000000000"
}'

{
  "status": "success"
}

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

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

What made this section unhelpful for you?

Endpoints

GET

GET

GET

POST

GET

POST

POST

POST

POST

POST

POST

What made this section unhelpful for you?

List campaigns

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?

Get campaign name

Query Parameters

Response

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 campaign status

Query Parameters

Response

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?

Set campaign name

Body Parameters

Response

Response Attributes

What made this section unhelpful for you?

Language Box

cURL

Ruby

Response

Body Parameters