API Key

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.

Languages
Servers
Instantly API Server

https://api.instantly.ai/

Mock server

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

Analytics

Endpoints related to analytics

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

API Key

Operations

API Key

API Key

idstring(uuid)read-onlyrequired
Example: "0198c3bf-589b-771c-966d-f962e5560a34"
namestringrequired
Example: "My API Key"
scopesArray of stringsrequired
Items Enum"all:all""all:create""all:read""all:update""all:delete""ai_agents:all""ai_agents:create""ai_agents:read""ai_agents:update""ai_agents:delete"
Example: ["campaigns:create"]
keystringread-onlyrequired
Example: "a1b2c3d4e5f6g7h8i9j0"
organization_idstring(uuid)read-onlyrequired
Example: "0198c3bf-589d-73e1-8a60-da80d71bad67"
timestamp_createdstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
timestamp_updatedstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
{
  "id": "0198c3bf-589b-771c-966d-f962e5560a34",
  "name": "My API Key",
  "scopes": [
    "campaigns:create"
  ],
  "key": "a1b2c3d4e5f6g7h8i9j0",
  "organization_id": "0198c3bf-589d-73e1-8a60-da80d71bad67",
  "timestamp_created": "2025-08-19T19:12:33.949Z",
  "timestamp_updated": "2025-08-19T19:12:33.949Z"
}

Create api key

Request

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

Bodyapplication/jsonrequired

The API Key to create

namestringrequired
Example: "My API Key"
scopesArray of stringsrequired
Items Enum"all:all""all:create""all:read""all:update""all:delete""ai_agents:all""ai_agents:create""ai_agents:read""ai_agents:update""ai_agents:delete"
Example: ["campaigns:create"]
curl -i -X POST \
  https://api.instantly.ai/api/v2/api-keys \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My API Key",
    "scopes": [
      "campaigns:create"
    ]
  }'

Responses

The API Key

Bodyapplication/json
idstring(uuid)read-onlyrequired
Example: "0198c3bf-589b-771c-966d-f962e5560a34"
namestringrequired
Example: "My API Key"
scopesArray of stringsrequired
Items Enum"all:all""all:create""all:read""all:update""all:delete""ai_agents:all""ai_agents:create""ai_agents:read""ai_agents:update""ai_agents:delete"
Example: ["campaigns:create"]
keystringread-onlyrequired
Example: "a1b2c3d4e5f6g7h8i9j0"
organization_idstring(uuid)read-onlyrequired
Example: "0198c3bf-589d-73e1-8a60-da80d71bad67"
timestamp_createdstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
timestamp_updatedstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
Response
application/json
{
  "id": "0198c3bf-589b-771c-966d-f962e5560a34",
  "name": "My API Key",
  "scopes": [
    "campaigns:create"
  ],
  "key": "a1b2c3d4e5f6g7h8i9j0",
  "organization_id": "0198c3bf-589d-73e1-8a60-da80d71bad67",
  "timestamp_created": "2025-08-19T19:12:33.949Z",
  "timestamp_updated": "2025-08-19T19:12:33.949Z"
}

List api key

Request

Requires one of the following scopes: api_keys:read, api_keys: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/api-keys?limit=10&starting_after=01956fbd-0eb1-72db-a565-82977a586084' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of API Key

Bodyapplication/json
itemsArray of objects(API Key)required
items[].​idstring(uuid)read-onlyrequired
Example: "0198c3bf-589b-771c-966d-f962e5560a34"
items[].​namestringrequired
Example: "My API Key"
items[].​scopesArray of stringsrequired
Items Enum"all:all""all:create""all:read""all:update""all:delete""ai_agents:all""ai_agents:create""ai_agents:read""ai_agents:update""ai_agents:delete"
Example: ["campaigns:create"]
items[].​keystringread-onlyrequired
Example: "a1b2c3d4e5f6g7h8i9j0"
items[].​organization_idstring(uuid)read-onlyrequired
Example: "0198c3bf-589d-73e1-8a60-da80d71bad67"
items[].​timestamp_createdstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
items[].​timestamp_updatedstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
next_starting_afterstring

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

Example: "0198c3bf-6a5f-7287-bf03-214b3e93120e"
Response
application/json
{
  "items": [
    { … }
  ],
  "next_starting_after": "0198c3bf-6a5f-7287-bf03-214b3e93120e"
}

Delete api key

Request

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

Path
idstring(uuid)required

The ID of the item to delete

Example: 0198c3bf-6a60-722b-8b03-1862b61f3869
Bodyapplication/json
null
curl -i -X DELETE \
  https://api.instantly.ai/api/v2/api-keys/0198c3bf-6a60-722b-8b03-1862b61f3869 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json'

Responses

The deleted API Key

Bodyapplication/json
idstring(uuid)read-onlyrequired
Example: "0198c3bf-589b-771c-966d-f962e5560a34"
namestringrequired
Example: "My API Key"
scopesArray of stringsrequired
Items Enum"all:all""all:create""all:read""all:update""all:delete""ai_agents:all""ai_agents:create""ai_agents:read""ai_agents:update""ai_agents:delete"
Example: ["campaigns:create"]
keystringread-onlyrequired
Example: "a1b2c3d4e5f6g7h8i9j0"
organization_idstring(uuid)read-onlyrequired
Example: "0198c3bf-589d-73e1-8a60-da80d71bad67"
timestamp_createdstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
timestamp_updatedstring(date-time)read-onlyrequired
Example: "2025-08-19T19:12:33.949Z"
Response
application/json
{
  "id": "0198c3bf-589b-771c-966d-f962e5560a34",
  "name": "My API Key",
  "scopes": [
    "campaigns:create"
  ],
  "key": "a1b2c3d4e5f6g7h8i9j0",
  "organization_id": "0198c3bf-589d-73e1-8a60-da80d71bad67",
  "timestamp_created": "2025-08-19T19:12:33.949Z",
  "timestamp_updated": "2025-08-19T19:12:33.949Z"
}

Account Campaign Mapping

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

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

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

Schemas