API explorerChangelog
API explorer
Changelog

Theme switcher

Introduction

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

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

Finding your API key 🗝️

1

Go to Instantly Dashboard

The first step to using the Instantly API platform is to find your API key.

2

Go to Settings → Integrations

To get to your API key, go to your: Instantly Dashboard → Settings → Integrations → API

https://app.instantly.ai/app/settings/integrations

3

Retrieve your API key

The API key helps authenticate your incoming requests and is unique per Instantly workspace.

You need to be on the Hypergrowth plan (or above) to be able to access the API key.

1 2 3 4 5 To get to your API key, go to your: Instantly Dashboard → Settings → Integrations → API https: //app.instantly.ai/app/settings/integrations

Campaign

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
GET
GET
POST
GET
POST
POST
POST
POST
POST
POST

Analytics

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Base URL

Production:

https://api.instantly.ai/api

Lead

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

POST
GET
POST
POST
POST
POST
POST

Blocklist

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

POST
POST

Account

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
POST
GET
POST
POST
POST
POST

Unibox

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

GET
GET
POST
POST

Tags

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

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.
Was this section helpful?

What made this section unhelpful for you?

Endpoints

POST
GET
GET
PATCH
DELETE
POST
Was this section helpful?

What made this section unhelpful for you?

Create a new Tag

Create a new custom tag and assign it to specified resources if resource_ids and resource_type are provided.

For resource_type 1 (ACCOUNT), only email addresses are accepted. For resource_type 2 (CAMPAIGN), only UUIDs are accepted. Please ensure your input matches the corresponding format based on the resource_type specified.

Heads up! if you are still unsure about what resource_type to use, you should check this guide first

Query Parameters

api_keystring Required

Your API Key

Body Parameters

labelstring Required

Specifies the label or name of the tag

descriptionstring

Provides a description or additional information about the tag

Response

200
Object
Successfully created the tag.

Response Attributes

idstring Required

The unique tag ID

timestamp_createdstring Required

The timestamp when the tag was created

timestamp_updatedstring Required

The timestamp of the last update of this tag

organization_idstring Required

The workspace id

labelstring Required

Tag label

descriptionstring

Tag description

400
Object
Bad Request

Response Attributes

statusCodenumber

The status code of the request

errorstring

The type of error

messagestring

Error message

500
Object
Internal server error

Response Attributes

statusCodenumber
errorstring
messagestring
Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/custom-tag?api_key=API_KEY

Select
1 2 3 4 5 curl --location 'https://api.instantly.ai/api/v1/custom-tag?api_key=API_KEY' \ --data '{ "label": "High Delivery", "description": "High Delivery Accounts" }'

Response

{
  "id": "97a30801-2195-4b2e-9f44-00ba081a0e9f",
  "timestamp_created": "2024-05-13T16:57:39.940Z",
  "timestamp_updated": "2024-05-13T16:57:39.940Z",
  "organization_id": "75a38123-07b5-1289-a7c2-b432ea1622d2",
  "label": "High Delivery",
  "description": "High Delivery Accounts"
}
Was this section helpful?

What made this section unhelpful for you?

Get a Tag by id

Retrieve information about a specific custom tag.

Query Parameters

api_keystring Required

Your API Key

Path Parameters

tag_idstring Required

Tag ID

Response

200
Object
Successfully retrieved the tag and its associated resources.

Response Attributes

idstring Required

The unique tag ID

timestamp_createdstring Required

The timestamp when the tag was created

timestamp_updatedstring Required

The timestamp of the last update of this tag

organization_idstring Required

The workspace id

labelstring

Tag label

descriptionstring

Tag description

404
Object
Tag not found

Response Attributes

statusCodenumber Required

Request status code

errorstring Required

Error type

messagestring Required

Error message

Was this section helpful?

What made this section unhelpful for you?

Language Box

GET

/v1/custom-tag/{tag_id}?api_key=API_KEY

Select
1 curl --location 'https://api.instantly.ai/api/v1/custom-tag/97a30801-2195-4b2e-9f44-00ba081a0e9f?api_key=API_KEY' \

Response

{
  "id": "97a30801-2195-4b2e-9f44-00ba081a0e9f",
  "timestamp_created": "2024-05-13T16:57:39.940Z",
  "timestamp_updated": "2024-05-13T16:57:39.940Z",
  "organization_id": "75a38123-07b5-1289-a7c2-b432ea1622d2",
  "label": "High Delivery",
  "description": "High Delivery Accounts"
}
Was this section helpful?

What made this section unhelpful for you?

List Tags

Retrieve a list of all custom tags available in your organization, optionally filtered by certain criteria.

Query Parameters

api_keystring Required

Your API Key

limitstring

Limits the number of tags returned in the response. Maximum value is 100.

skipstring

Skips the specified number of tags in the response.

searchstring

Searches for tags based on the provided label.

resource_idsstring

Retrieves tags associated with the specified resource IDs. Multiple IDs can be provided as a comma-separated string.

tag_idsstring

Retrieves tags based on the provided tag IDs. Multiple IDs can be provided as a comma-separated string.

Response

200
Object
Successfully retrieved the requested tags.

Response Attributes

dataarray Required

Show child attributes

limitnumber Required

The number of entries to fetch

skipnumber Required

The number of entries skipped

400
Object
Bad Request

Response Attributes

statusCodenumber

Request status code

errorstring

Error name

messagestring

Error message

Was this section helpful?

What made this section unhelpful for you?

Language Box

GET

/v1/custom-tag?api_key=API_KEY&limit=10&skip=&search=&resource_ids=jondoe@example.com,bruce@wayne.com&tag_ids=c7274042-681a-476e-8621-7ddec2facc59,32bfb7ba-c42f-4408-8976-01581faf1eb4

Select
1 curl --location 'https://api.instantly.ai/api/v1/custom-tag?api_key=API_KEY&limit=10&resource_ids=jondoe%40example.com%2Cbruce%40wayne.com&tag_ids=c7274042-681a-476e-8621-7ddec2facc59%2C32bfb7ba-c42f-4408-8976-01581faf1eb4' \

Response

{
  "data": [
    {
      "id": "97a30801-2195-4b2e-9f44-00ba081a0e9f",
      "timestamp_created": "2024-05-13T16:57:39.940Z",
      "timestamp_updated": "2024-05-13T17:04:39.572Z",
      "organization_id": "75a31235-07b5-1234-a7c2-b432ea1622d2",
      "label": "My first custom tag",
      "description": ""
    },
    {
      "id": "1e229e97-24ba-4975-a642-7843d0c86760",
      "timestamp_created": "2024-05-13T15:45:58.844Z",
      "timestamp_updated": "2024-05-13T15:45:58.844Z",
      "organization_id": "75a31235-07b5-1234-a7c2-b432ea1622d2",
      "label": "My second custom tag",
      "description": ""
    },
    {
      "id": "cf783362-acf4-43ac-95f3-928abc02a56c",
      "timestamp_created": "2024-05-13T15:45:21.188Z",
      "timestamp_updated": "2024-05-13T15:45:21.188Z",
      "organization_id": "75a31235-07b5-1234-a7c2-b432ea1622d2",
      "label": "High Delivery",
      "description": null
    },
    {
      "id": "c7274042-681a-476e-8621-7ddec2facc59",
      "timestamp_created": "2024-05-13T15:44:47.423Z",
      "timestamp_updated": "2024-05-13T15:44:47.423Z",
      "organization_id": "75a31235-07b5-1234-a7c2-b432ea1622d2",
      "label": "Important",
      "description": null
    },
    {
      "id": "32bfb7ba-c42f-4408-8976-01581faf1eb4",
      "timestamp_created": "2024-05-13T15:44:37.023Z",
      "timestamp_updated": "2024-05-13T15:44:37.023Z",
      "organization_id": "75a31235-07b5-1234-a7c2-b432ea1622d2",
      "label": "High Value",
      "description": ""
    }
  ],
  "limit": 5,
  "skip": null
}
Was this section helpful?

What made this section unhelpful for you?

Update Tag

Update an existing custom tag by modifying the label or description.

Use the Update Tag endpoint to modify only the label or description, if you want to assign or unassign resources use this endpoint instead

Query Parameters

api_keystring Required

Your API Key

Path Parameters

:idstring

The tag ID

Body Parameters

labelstring Required

The new label for the tag

descriptionstring

The new description for the tag

Response

200
Object
Successfully updated the custom tag.

Response Attributes

idstring Required

The unique tag ID

timestamp_createdstring Required

The timestamp when the tag was created

timestamp_updatedstring Required

The timestamp of the last update of this tag

organization_idstring Required

The workspace id

labelstring Required

Tag label

descriptionstring

Tag description

404
Object
Tag not found

Response Attributes

statusCodenumber Required

Request status code

errorstring Required

Error type

messagestring Required

Error message

Was this section helpful?

What made this section unhelpful for you?

Language Box

PATCH

/v1/custom-tag/{:id}?api_key=API_KEY

Select
1 2 3 4 5 curl --location --request PATCH 'https://api.instantly.ai/api/v1/custom-tag/97a30801-2195-4b2e-9f44-00ba081a0e9f?api_key=API_KEY' \ --data '{ "label": "My new tag label", "description": "New Tag" }'

Response

{
  "id": "97a30801-2195-4b2e-9f44-00ba081a0e9f",
  "timestamp_created": "2024-05-13T16:57:39.940Z",
  "timestamp_updated": "2024-05-13T17:45:05.883Z",
  "organization_id": "75a38254-07b5-4569-a7c2-b432ea1622d2",
  "label": "My new tag label",
  "description": "New Tag"
}
Was this section helpful?

What made this section unhelpful for you?

Delete a Tag

Delete an existing custom tag.

We cannot recover your tag after you delete it.

Query Parameters

api_keystring Required

Your API Key

Path Parameters

tag_idstring Required

The ID of the custom tag to be deleted

Response

200
Object
The tag that was deleted

Response Attributes

idstring

The unique tag ID

timestamp_createdstring

The timestamp when the tag was created

timestamp_updatedstring

The timestamp of the last update of this tag

organization_idstring

The workspace id

labelstring

Tag label

descriptionstring

Tag description

404
Object
Not Found

Response Attributes

statusCodenumber Required

Request status code

errorstring Required

Error code

messagestring Required

Error message

Was this section helpful?

What made this section unhelpful for you?

Language Box

DELETE

/v1/custom-tag/{tag_id}?api_key=API_KEY

Select
1 curl --location --request DELETE 'https://api.instantly.ai/api/v1/custom-tag/97a30801-2195-4b2e-9f44-00ba081a0e9f?api_key=API_KEY' \

Response

{
  "id": "97a30801-2195-4b2e-9f44-00ba081a0e9f",
  "timestamp_created": "2024-05-13T16:57:39.940Z",
  "timestamp_updated": "2024-05-13T16:57:39.940Z",
  "organization_id": "75a38123-07b5-1289-a7c2-b432ea1622d2",
  "label": "High Delivery",
  "description": "High Delivery Accounts"
}
Was this section helpful?

What made this section unhelpful for you?

Assign or unassign a tag

Toggle the assignment status of one or more custom tags for specific resources, either assigning or unassigning the custom tags as required.

For resource_type 1 (ACCOUNT), only email addresses are accepted. For resource_type 2 (CAMPAIGN), only UUIDs are accepted. Please ensure your input matches the corresponding format based on the resource_type specified.

Heads up! if you are still unsure about what resource_type to use, you should check this guide first

Query Parameters

api_keystring Required

Your API Key

Body Parameters

tag_idsarray Required

Specifies the unique identifiers of the tags to be assigned or unassigned to the resources.

Show child attributes

resource_typenumber (int32)Required

Resource Type

Enum values:
1
Use 1 for ACCOUNTS
2
Use 2 for CAMPAIGNS
resource_idsarray Required

The IDs of the resources to assign or unassign the tags to.

Show child attributes

assignboolean (binary)Required

Specifies whether to assign (true) or unassign (false) the tags to the resources. If not provided, the default value is true.

Response

200
Object
Successfully assigned the tags to the resources.

Response Attributes

successboolean
messagestring
200
Object
Successfully unassigned the tags to the resources.

Response Attributes

successboolean
messagestring
400
Object
Bad Request

Response Attributes

statusCodenumber

Request code

errorstring

Error type

messagestring

Error messag

404
Object
Not found

Response Attributes

statusCodenumber

Status code

errorstring

Error type

messagestring

Error message

Was this section helpful?

What made this section unhelpful for you?

Language Box

POST

/v1/custom-tag/toggle-tag-resource?api_key=API_KEY

Select
1 2 3 4 5 6 7 8 9 10 11 12 13 14 curl --location 'https://api.instantly.ai/api/v1/custom-tag/toggle-tag-resource?api_key=API_KEY' \ --data-raw '{ "tag_ids": [ "87a30801-2195-4b2e-9f44-00ba081a0e9f", "98a30801-9521-9f44-4b2e-081a0e9f00ba", "32bfb7ba-c42f-4408-8976-01581faf1eb4" ], "resource_type": 1, "resource_ids": [ "johndoe@instantly.ai", "foobar@instantly.ai" ], "assign": true }'

Response

{
  "success": true,
  "message": "Tag assigned successfully"
}
Was this section helpful?

What made this section unhelpful for you?

Email Verification

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

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.

  1. Submitting a verification job
  2. Checking the status of a verification job

Endpoints

POST
GET

Custom Tracking Domain

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

Notice: This API (Version 1) has been deprecated. Please refer to the API v2 documentation for the latest version.

Endpoints

POST
GET
DELETE