Managing cold email campaigns becomes much easier when your email data is connected with your own tools, dashboards, or workflows. But many developers face the same problem: how do you actually fetch Instantly Unibox emails, replies, and conversations through the API?
If you are building a CRM integration, AI sales assistant, reporting dashboard, or automated follow-up system, manually checking the Instantly inbox is not practical. You need a reliable way to pull email data programmatically.
That is where the Instantly API v2 comes in.
With the updated API, developers can fetch Unibox emails, filter replies, access conversation threads, manage pagination, and connect outreach data with external applications.
In this guide, you will learn:
How to authenticate with Instantly API v2
How to fetch Unibox emails
How to get only real replies
How to filter Primary emails instead of "Others"
How pagination works
Polling vs webhooks
Common API errors and fixes
Working Python and JavaScript examples
Whether you are building sales automation tools or integrating Instantly data into your own platform, this guide covers everything you need.
Before You Start: Instantly API Key and Required Access
Before making API requests, you need an active Instantly account with API access and a valid API key.
Generate Your Instantly API Key
To create an API key:
Open your Instantly account
Go to Settings
Open Integrations
Select API Keys
Create a new API key
Make sure you store your API key securely because it is only shown once during creation.
Avoid placing API keys directly inside public code repositories.
Required API Scopes
The email endpoint requires one of the following scopes:
emails:reademails:allall:readall:all
These permissions allow your application to access email data from Unibox.
Instantly API Plan Requirements
API access requires a paid Outreach plan.
If your account does not have the required plan, the API may return:
This is different from an authentication problem.
Instantly API v1 vs v2: What Changed?
Instantly updated its API structure by replacing the older v1 endpoints with the newer v2 system.
The biggest changes include:
Feature | API v1 | API v2 |
|---|---|---|
Email endpoint |
|
|
Authentication | API key parameter | Bearer token |
Pagination | Offset-based | Cursor-based |
Naming | Inconsistent fields | snake_case format |
API Authentication Changed
Older API versions used API keys differently.
API v2 requires a Bearer token:
Example:
Pagination Method Changed
API v1 used offset pagination.
API v2 uses cursor pagination with:
This makes retrieving large amounts of email data more efficie
How To Fetch Unibox Emails Using Instantly API v2
The main endpoint for retrieving Unibox emails is:
Your request should include authentication headers:
Basic API Request Example
The response contains email objects with information such as:
Subject
Email body
Lead information
Thread ID
Sending account
Read status
Interest status
Instantly API Email Parameters Explained
The /api/v2/emails endpoint supports multiple filters.
Understanding these parameters helps you retrieve exactly the data you need.
Parameter | Type | Description |
|---|---|---|
| Integer | Number of emails per request |
| String | Pagination cursor |
| String | Search emails or threads |
| UUID | Filter by campaign |
| UUID | Filter by lead list |
| String | Filter by lead email |
| String | Filter sending accounts |
| String | Received, sent, or manual |
| String | Primary, Others, or All |
| Boolean | Filter unread emails |
| Boolean | Return latest email only |
| UUID | Filter assigned users |
How To Fetch Only Replies From Instantly Unibox
One of the most common API requirements is:
"I only want replies from prospects."
By default, your API response may include different types of emails.
To fetch only received replies, use:
To get only Primary replies:
To return only the latest message from each conversation:
Complete Reply Fetch Request
This returns:
Prospect replies
Primary inbox messages
Latest conversation messages
Why You Are Getting "Others" Instead of Primary Emails
Instantly Unibox separates messages into two categories:
Primary
Important conversations and replies.
API value:
Others
Less important messages.
API value:
All Emails
To retrieve everything:
Fixing the Primary Inbox Issue
If your API only returns "Others", you are probably missing the mode parameter.
Use:
You can also check the email object:
This confirms that the email belongs to the Primary category.
Instantly API Pagination Explained
When retrieving many emails, you cannot request everything at once.
Instantly API v2 uses cursor-based pagination.
The API response includes:
The next cursor is used in your following request.
Pagination Process
Send your first API request
Receive email results
Save
next_starting_afterSend it with your next request
Continue until no cursor remains
Frequently Asked Questions About Instantly API v2
How do I fetch emails from Instantly Unibox API?
You can fetch Instantly Unibox emails using the API v2 endpoint:
You need:
A valid Instantly API key
Correct API permissions
Bearer token authentication
You can also use filters like campaign ID, lead email, email type, and inbox mode to retrieve specific messages.
How do I fetch only replies from Instantly API?
To fetch only replies, use these parameters:
This combination returns received replies from the Primary inbox and removes unnecessary messages.
Why am I only getting "Others" emails from Instantly API?
Instantly Unibox separates emails into:
Primary
Others
If you are receiving only "Others", check your API request.
Use:
to retrieve Primary emails.
You can also check the is_focused field in the response to confirm the inbox category.
Is Instantly API v1 still available?
No. Instantly deprecated the v1 API, including the old Unibox email endpoint.
The previous endpoint:
was replaced with:
API v2 now uses Bearer authentication, improved field naming, and cursor-based pagination.
What is the Instantly API v2 rate limit?
The Instantly email endpoint has a limit of:
20 requests per minute
If you receive a:
response, slow down your requests and retry after a short delay.
Do I need a paid Instantly plan to use the API?
Yes.
API access requires an active paid Outreach plan.
If your account does not have API access, you may receive:
What is the difference between polling and webhooks in Instantly API?
Polling
Your application regularly asks Instantly:
"Are there any new emails?"
Useful for:
Reports
Data exports
Historical syncing
Webhooks
Instantly sends information automatically when an event happens.
Useful for:
Real-time reply notifications
CRM updates
Automated workflows
How do I get the latest email from a conversation thread?
Use:
This returns only the newest message from each email conversation instead of every message in the thread.
Can I filter Instantly emails by campaign?
Yes.
Use:
This allows you to retrieve emails from a specific outreach campaign.
Can I search specific leads using Instantly API?
Yes.
You can filter emails using:
or:
For example, you can search by:
Lead email address
Thread ID
Conversation data
How can I integrate Instantly replies with my CRM?
You can connect Instantly API data with your CRM by:
Fetching replies through API v2
Processing email data
Matching leads
Updating CRM records
For real-time workflows, webhooks are usually the better option.
Conclusion
The Instantly API v2 provides developers with a flexible way to access Unibox emails, replies, and conversation data. Whether you are building a CRM integration, analytics dashboard, or automated sales workflow, understanding the correct API parameters is essential.
The most important points are:
Use
/api/v2/emailsfor fetching emailsAuthenticate with Bearer API keys
Use
email_type=receivedfor repliesUse
mode=emode_focusedfor Primary inbox messagesUse pagination for large datasets
Use webhooks for real-time automation
With the right API setup, businesses can turn Instantly email data into powerful automation workflows and improve their outbound sales operations.
