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

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

Endpoints

GET

POST

Note: The body of the email object is only sent when you have preview_only=false (i.e., the default state is to send the content preview only). The body object may have a property called text and/or html, depending on the original content of the email.

The email_type parameter now accepts a new value manual. When applied, it will return the following email types:

Sent manually through the Unibox
Received emails (responses from leads)
Emails scheduled to be sent (from the Unibox)

Query Parameters

api_keystring Required

Your API Key

preview_onlystring

Set to false if you only want the email content's preview and not the full body

leadstring

Email address of lead (optional) - only fetch emails for a specific lead

campaign_idstring

Campaign id (optional) - only fetch emails for a specific campaign

sent_emailsstring

Set to true if you only want to fetch sent emails - only

email_typestring

Email type, read below for details

Enum values:

sent

A sent email - either through a campaign, or in Unibox

received

A received email - either a campaign response, or manual response

all

All types of emails

manual

Any type of email EXCEPT emails sent by campaigns

latest_of_threadstring

Set to true if you want to only fetch the latest email per thread

page_trailstring

Used for pagination - returned in the response

Response

200

Object

Response Attributes

page_trailstring

Used for pagination - you can pass this on to fetch the next page

dataarray

Show child attributes

curl --location 'https://api.instantly.ai/api/v1/unibox/emails?api_key=API_KEY&preview_only=true&lead=mylead%40gmail.com&campaign_id=00000000-0000-0000-0000-000000000000&sent_emails=false&email_type=all&latest_of_thread=false' \

{
  "page_trail": "2024-02-28T11:48:15.000Z",
  "data": [
    {
      "id": "018d159f-d7d6-7a00-8711-82ac3d610ffb",
      "message_id": "<launchwithinstantly.com-1705456802@instantly.ai>",
      "is_unread": 1,
      "lead": "mylead@gmail.com",
      "campaign_id": "00000000-0000-0000-0000-000000000000",
      "from_address_email": "john@instantly.ai",
      "from_address_json": [
        {
          "address": "john@instantly.ai",
          "name": "John Doe"
        }
      ],
      "ai_interest_value": null,
      "reminder_ts": null,
      "i_status": "1",
      "subject": "My subject line",
      "timestamp_created": "2024-01-17T04:13:33.000Z",
      "content_preview": "Hello, did you want to catch...",
      "body": {
        "text": "Hello, did you want to catch the game next week?",
        "html": null
      },
      "thread_id": "q2amCFRXCdNfe5ADMBmsEPc9nU",
      "eaccount": "me@email.com",
      "to_address_email_list": "me@email.com",
      "to_address_json": [
        {
          "address": "me@email.com",
          "name": ""
        }
      ],
      "ue_type": 2,
      "scheduled_at": null,
      "cc_address_email_list": null,
      "cc_address_json": null,
      "bcc_address_email_list": null
    }
  ]
}

Get the number of unread emails in the “Primary” box.

Query Parameters

api_keystring Required

Your API Key

Response

200

Object

Response Attributes

countnumber

curl --location 'https://api.instantly.ai/api/v1/unibox/emails/count/unread?api_key=API_KEY' \

{
  "count": 10
}

This endpoint marks all emails in a thread as read.

The thread id should be passed in the URL and not the POST body (see example code).

Path Parameters

thread_idstring

Thread id that you want to mark as read

Body Parameters

api_keystring Required

Your API key

Response

200

Object

Response Attributes

countnumber

Number of changed rows

curl --location 'https://api.instantly.ai/api/v1/unibox/threads/your-thread-id/mark-as-read' \
--data '{
  "api_key": ""
}'

{
  "count": 1
}

Send an email reply through Unibox

Query Parameters

api_keystring

Your API Key

Body Parameters

reply_to_uuidstring Required

The UUID of the email being replied to.

subjectstring Required

The subject of the email reply.

fromstring Required

The email address of the sender.

tostring Required

The email address of the recipient.

bodystring Required

The body of the email reply.

ccstring

The email addresses to be included in the CC field.

bccstring

The email addresses to be included in the BCC field.

reminder_tsstring

The timestamp for setting a reminder for the email reply.

scheduled_atstring

The timestamp for scheduling the email reply to be sent.

Response

200

Object

The email reply was sent successfully.

Response Attributes

statusstring

message_idstring

400

Object

Invalid request data or validation errors.

Response Attributes

messagestring

404

Object

The email being replied to does not exist.

Response Attributes

messagestring

500

Object

An error occurred while sending the email reply.

Response Attributes

messagestring

curl --location 'https://api.instantly.ai/api/v1/unibox/emails/reply?api_key=API_KEY' \
--data-raw '{
  "reply_to_uuid": "00000000-0000-0000-0000-000000000001",
  "subject": "Re: Subject",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "body": "Reply body",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "reminder_ts": "2024-05-10T10:00:00Z",
  "scheduled_at": "2024-05-11T10:00:00Z"
}'

{
  "status": "success",
  "message_id": "00000000-0000-0000-0000-000000000002"
}

The Unibox API docs are currently being tested and deployed; we'll add more sections soon. For early access, please contact support.

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

Endpoints

GET

POST

GET

POST

POST

POST

POST

Unibox

What made this section unhelpful for you?

Endpoints

GET

GET

POST

POST

What made this section unhelpful for you?

Emails | List

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?

Emails | Count Unread

Query Parameters

Response

Response Attributes

What made this section unhelpful for you?

Language Box

cURL

Ruby

Python

PHP

Java

Response