# Instantly

> Email outreach and lead generation platform for managing campaigns, creating leads, and tracking email performance.

Source: https://cotera.co/docs/reference/tools/individual-tools/instantly

---

**Authentication Type:** API Key\
**Description:** Email outreach and lead generation platform for managing campaigns, creating leads, and tracking email performance with comprehensive analytics.

***

## Authentication

To authenticate, you'll need an Instantly API key. Learn how to get one in the [Instantly Developer documentation](https://developer.instantly.ai/getting-started/getting-started).

***

## Campaigns

Manage email outreach campaigns in Instantly with full CRUD operations.

### List Campaigns

Retrieve a paginated list of campaigns from your Instantly workspace with optional filtering by status, tag, or AI sales agent.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (nullable): Maximum number of campaigns to return
* **starting\_after** `string` (nullable): Campaign ID for cursor-based pagination
* **search** `string` (nullable): Search term to filter campaigns by name
* **tag\_ids** `string` (nullable): Comma-separated tag IDs to filter campaigns
* **ai\_sales\_agent\_id** `string` (nullable): Filter by AI sales agent ID
* **status** `number` (nullable): Filter by campaign status

**Returns:**

* **items** `array of objects`: Campaign objects with fields:
  * **id** `string`: Campaign unique identifier
  * **name** `string`: Campaign name
  * **status** `number`: Campaign status
  * **timestamp\_created** `string`: Creation timestamp
  * **timestamp\_updated** `string`: Last updated timestamp
  * **organization** `string`: Organization ID
  * **pl\_value** `string` (nullable): Pipeline value
  * **is\_evergreen** `boolean` (nullable): Whether the campaign is evergreen
  * **daily\_limit** `number` (nullable): Daily email send limit
  * **stop\_on\_reply** `boolean` (nullable): Stop sending on reply
  * **email\_gap** `number` (nullable): Gap between emails in minutes
  * **random\_wait\_max** `number` (nullable): Maximum random wait time
  * **text\_only** `boolean` (nullable): Send text-only emails
  * **email\_list** `array of strings` (nullable): Sending email addresses
  * **link\_tracking** `boolean` (nullable): Track link clicks
  * **open\_tracking** `boolean` (nullable): Track email opens
  * **daily\_max\_leads** `number` (nullable): Max new leads to contact per day
  * **prioritize\_new\_leads** `boolean` (nullable): Prioritize new leads
* **next\_starting\_after** `string` (nullable): Cursor for the next page of results

**Example Usage:**

```json
{
  "limit": 25,
  "starting_after": null,
  "search": "Q4 outreach",
  "status": 1
}
```

### Get Campaign

Retrieve full details of a specific campaign by ID, including all configuration settings.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Unique identifier of the campaign to retrieve

**Returns:**

Campaign object with all fields from List Campaigns plus:

* **first\_email\_text\_only** `boolean` (nullable): Send first email as text-only
* **email\_tag\_list** `array of strings` (nullable): Email tags associated with the campaign
* **stop\_on\_auto\_reply** `boolean` (nullable): Stop on auto-reply detection
* **auto\_variant\_select** `boolean` (nullable): Automatically select best variant
* **match\_lead\_esp** `boolean` (nullable): Match lead email service provider
* **stop\_for\_company** `boolean` (nullable): Stop contacting leads from same company on reply
* **insert\_unsubscribe\_header** `boolean` (nullable): Insert unsubscribe header in emails
* **allow\_risky\_contacts** `boolean` (nullable): Allow contacts flagged as risky
* **disable\_bounce\_protect** `boolean` (nullable): Disable bounce protection

**Example Usage:**

```json
{
  "id": "camp_123456"
}
```

### Create Campaign

Create a new email outreach campaign in Instantly with full configuration options.

**Operation Type:** Mutation (Write)

**Parameters:**

* **name** `string` (required): Campaign name
* **campaign\_schedule** `object` (required): Schedule configuration object (see Instantly docs for structure)
* **pl\_value** `string` (nullable): Pipeline value for the campaign
* **is\_evergreen** `boolean` (nullable): Set campaign as evergreen
* **sequences** `object` (nullable): Email sequence configuration
* **email\_gap** `number` (nullable): Minutes between emails
* **random\_wait\_max** `number` (nullable): Maximum random wait time in minutes
* **text\_only** `boolean` (nullable): Send text-only emails
* **first\_email\_text\_only** `boolean` (nullable): Send first email as text-only
* **email\_list** `array of strings` (nullable): Sending email addresses
* **daily\_limit** `number` (nullable): Daily email send limit
* **stop\_on\_reply** `boolean` (nullable): Stop sequence on reply
* **email\_tag\_list** `array of strings` (nullable): Email tag IDs for this campaign
* **link\_tracking** `boolean` (nullable): Enable link click tracking
* **open\_tracking** `boolean` (nullable): Enable email open tracking
* **stop\_on\_auto\_reply** `boolean` (nullable): Stop on auto-reply detection
* **daily\_max\_leads** `number` (nullable): Max new leads contacted per day
* **prioritize\_new\_leads** `boolean` (nullable): Prioritize new leads over follow-ups
* **auto\_variant\_select** `boolean` (nullable): Automatically select best A/B variant
* **match\_lead\_esp** `boolean` (nullable): Match lead email service provider
* **stop\_for\_company** `boolean` (nullable): Stop entire company on reply
* **insert\_unsubscribe\_header** `boolean` (nullable): Insert unsubscribe header
* **allow\_risky\_contacts** `boolean` (nullable): Allow risky contacts
* **disable\_bounce\_protect** `boolean` (nullable): Disable bounce protection
* **cc\_list** `array of strings` (nullable): Addresses to CC on emails
* **bcc\_list** `array of strings` (nullable): Addresses to BCC on emails
* **owned\_by** `string` (nullable): User ID of the campaign owner

**Returns:**

* Created campaign object (same structure as Get Campaign response)

**Example Usage:**

```json
{
  "name": "Q1 2025 Outreach",
  "campaign_schedule": {
    "schedules": [
      {
        "name": "My Schedule",
        "timing": { "from": "08:00", "to": "17:00" },
        "days": {
          "sun": false,
          "mon": true,
          "tue": true,
          "wed": true,
          "thu": true,
          "fri": true,
          "sat": false
        },
        "timezone": "America/New_York"
      }
    ]
  },
  "daily_limit": 50,
  "stop_on_reply": true,
  "open_tracking": true,
  "link_tracking": true
}
```

### Add Campaign Variables

Add custom variable names to an Instantly campaign, enabling personalization placeholders for use in email sequences.

**Operation Type:** Mutation (Write)

**Parameters:**

* **id** `string` (required): Campaign ID to add variables to
* **variables** `array of strings` (required): List of custom variable names to register on the campaign

**Returns:**

* Updated campaign object (same structure as Get Campaign response)

**Example Usage:**

```json
{
  "id": "camp_123456",
  "variables": ["company_size", "industry", "pain_point"]
}
```

***

## Leads

Manage leads in your Instantly campaigns with full CRUD operations.

### Create Lead

Create a new lead in Instantly with email, name, company information, and campaign association. Returns the created lead with all metadata.

**Operation Type:** Mutation (Write)

**Parameters:**

* **email** `string` (required): Email address of the lead
* **first\_name** `string` (nullable): First name of the lead
* **last\_name** `string` (nullable): Last name of the lead
* **company\_name** `string` (nullable): Company name of the lead
* **phone** `string` (nullable): Phone number of the lead
* **website** `string` (nullable): Website of the lead
* **personalization** `string` (nullable): Personalization note for the lead
* **campaign** `string` (nullable): Campaign ID to associate the lead with
* **list\_id** `string` (nullable): List ID to associate the lead with
* **lt\_interest\_status** `number` (nullable): Lead interest status (0=Out of Office, 1=Interested, 2=Meeting Booked, 3=Meeting Completed, 4=Closed, -1=Not Interested, -2=Wrong Person, -3=Lost)
* **pl\_value\_lead** `string` (nullable): Potential value of the lead
* **assigned\_to** `string` (nullable): ID of the user assigned to the lead
* **skip\_if\_in\_workspace** `boolean` (nullable): Whether to skip if the lead is already in the workspace
* **skip\_if\_in\_campaign** `boolean` (nullable): Whether to skip if the lead is already in the campaign
* **skip\_if\_in\_list** `boolean` (nullable): Whether to skip if the lead is already in the list
* **blocklist\_id** `string` (nullable): The ID of the blocklist to check for the lead
* **verify\_leads\_for\_lead\_finder** `boolean` (nullable): Whether to verify the leads for the lead finder
* **verify\_leads\_on\_import** `boolean` (nullable): Whether to verify the leads on import
* **custom\_variables** `object` (nullable): Custom variables - any metadata about the lead that is relevant to the campaign

**Returns:**

* **id** `string`: Unique identifier for the lead
* **timestamp\_created** `string`: Timestamp when the lead was created
* **timestamp\_updated** `string`: Timestamp when the lead was last updated
* **organization** `string`: Organization ID associated with the lead
* **status** `number`: Status of the lead (1=Active, -1=Bounced, -2=Unsubscribed, -3=Skipped)
* **email\_open\_count** `number`: Number of times the email was opened
* **email\_reply\_count** `number`: Number of times the email was replied to
* **email\_click\_count** `number`: Number of times the email was clicked
* **company\_domain** `string`: Company domain of the lead
* **campaign** `string` (nullable): Campaign ID associated with the lead
* **email** `string` (nullable): Email address of the lead
* **first\_name** `string` (nullable): First name of the lead
* **last\_name** `string` (nullable): Last name of the lead
* **company\_name** `string` (nullable): Company name of the lead
* **phone** `string` (nullable): Phone number of the lead
* **verification\_status** `number`: Email verification status
* **list\_id** `string` (nullable): List ID associated with the lead

**Example Usage:**

```json
{
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Example Corp",
  "phone": "+1-555-123-4567",
  "website": "https://example.com",
  "personalization": "Saw your recent article on LinkedIn",
  "campaign": "camp_123456",
  "list_id": "list_789",
  "lt_interest_status": 1,
  "pl_value_lead": "$5000",
  "custom_variables": {
    "source": "linkedin",
    "industry": "technology"
  }
}
```

### List Leads

Retrieve a paginated list of leads from your Instantly workspace with filtering options by campaign, list, status, and search terms.

**Operation Type:** Query (Read)

**Parameters:**

* **limit** `number` (nullable): Number of leads to return (1-100)
* **starting\_after** `string` (nullable): ID of the last lead in the previous page for pagination
* **search** `string` (nullable): Search term to filter leads
* **campaign\_id** `string` (nullable): Filter leads by campaign ID
* **list\_id** `string` (nullable): Filter leads by list ID
* **status** `array of numbers` (nullable): Filter leads by status array

**Returns:**

* **items** `array of objects`: Array of lead objects (same structure as Create Lead response)
* **next\_starting\_after** `string` (nullable): ID for pagination to get next set of results

**Example Usage:**

```json
{
  "limit": 50,
  "starting_after": null,
  "search": "acme",
  "campaign_id": "camp_123456",
  "list_id": null,
  "status": [1, -1]
}
```

### Get Lead

Retrieve detailed information about a specific lead by its unique identifier, including engagement metrics and campaign associations.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (required): Unique identifier of the lead to retrieve

**Returns:**

* Lead object (same structure as Create Lead response)

**Example Usage:**

```json
{
  "id": "lead_123456789"
}
```

***

## Analytics

Campaign analytics insights, overview metrics, daily and per-step performance.

### Get Campaign Analytics

Fetch aggregated campaign analytics for one or multiple campaigns over a date range.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (nullable): Single campaign ID to get analytics for
* **ids** `array of strings` (nullable): Array of campaign IDs to get analytics for
* **start\_date** `string` (nullable): Start date for analytics range
* **end\_date** `string` (nullable): End date for analytics range
* **exclude\_total\_leads\_count** `boolean` (nullable): Whether to exclude total leads count from results

**Returns:**

* Array of campaign analytics objects:
  * **campaign\_name** `string` (nullable): Campaign name
  * **campaign\_id** `string` (nullable): Campaign ID
  * **campaign\_status** `number` (nullable): Campaign status
  * **campaign\_is\_evergreen** `boolean` (nullable): Whether campaign is evergreen
  * **leads\_count** `number` (nullable): Total leads count
  * **contacted\_count** `number` (nullable): Number of leads contacted
  * **open\_count** `number` (nullable): Number of email opens
  * **reply\_count** `number` (nullable): Number of replies received
  * **link\_click\_count** `number` (nullable): Number of link clicks
  * **bounced\_count** `number` (nullable): Number of bounced emails
  * **unsubscribed\_count** `number` (nullable): Number of unsubscribes
  * **completed\_count** `number` (nullable): Number of completed sequences
  * **emails\_sent\_count** `number` (nullable): Total emails sent
  * **total\_opportunities** `number` (nullable): Total opportunities generated
  * **total\_opportunity\_value** `number` (nullable): Total value of opportunities

**Example Usage:**

```json
{
  "ids": ["camp_123", "camp_456"],
  "start_date": "2024-12-01",
  "end_date": "2024-12-31",
  "exclude_total_leads_count": false
}
```

### Get Campaign Analytics Overview

Fetch overall analytics overview across campaigns with optional status filtering.

**Operation Type:** Query (Read)

**Parameters:**

* **id** `string` (nullable): Single campaign ID to get overview for
* **ids** `array of strings` (nullable): Array of campaign IDs to get overview for
* **start\_date** `string` (nullable): Start date for overview range
* **end\_date** `string` (nullable): End date for overview range
* **campaign\_status** `number` (nullable): Filter by campaign status

**Returns:**

* **open\_count** `number` (nullable): Total opens count
* **open\_count\_unique** `number` (nullable): Unique opens count
* **link\_click\_count** `number` (nullable): Total link clicks
* **link\_click\_count\_unique** `number` (nullable): Unique link clicks
* **reply\_count** `number` (nullable): Total replies count
* **reply\_count\_unique** `number` (nullable): Unique replies count
* **bounced\_count** `number` (nullable): Total bounced emails
* **unsubscribed\_count** `number` (nullable): Total unsubscribes
* **completed\_count** `number` (nullable): Total completed sequences
* **emails\_sent\_count** `number` (nullable): Total emails sent
* **total\_opportunities** `number` (nullable): Total opportunities
* **total\_opportunity\_value** `number` (nullable): Total opportunity value
* **total\_interested** `number` (nullable): Total interested leads
* **total\_meeting\_booked** `number` (nullable): Total meetings booked
* **total\_meeting\_completed** `number` (nullable): Total meetings completed
* **total\_closed** `number` (nullable): Total closed deals

**Example Usage:**

```json
{
  "ids": ["camp_123", "camp_456"],
  "start_date": "2024-12-01",
  "end_date": "2024-12-31",
  "campaign_status": 1
}
```

### Get Daily Campaign Analytics

Fetch daily analytics time series for a campaign over a date range.

**Operation Type:** Query (Read)

**Parameters:**

* **campaign\_id** `string` (nullable): Campaign ID to get daily analytics for
* **start\_date** `string` (nullable): Start date for daily analytics
* **end\_date** `string` (nullable): End date for daily analytics
* **campaign\_status** `number` (nullable): Filter by campaign status

**Returns:**

* Array of daily analytics objects:
  * **date** `string` (nullable): Date for the analytics entry
  * **sent** `number` (nullable): Emails sent on this date
  * **opened** `number` (nullable): Emails opened on this date
  * **unique\_opened** `number` (nullable): Unique opens on this date
  * **replies** `number` (nullable): Replies received on this date
  * **unique\_replies** `number` (nullable): Unique replies on this date
  * **clicks** `number` (nullable): Link clicks on this date
  * **unique\_clicks** `number` (nullable): Unique clicks on this date

**Example Usage:**

```json
{
  "campaign_id": "camp_123456",
  "start_date": "2024-12-01",
  "end_date": "2024-12-31",
  "campaign_status": 1
}
```

### Get Campaign Steps Analytics

Fetch per-step analytics for a campaign over a date range.

**Operation Type:** Query (Read)

**Parameters:**

* **campaign\_id** `string` (nullable): Campaign ID to get step analytics for
* **start\_date** `string` (nullable): Start date for step analytics
* **end\_date** `string` (nullable): End date for step analytics

**Returns:**

* Array of step analytics objects:
  * **step** `string` (nullable): Step identifier
  * **variant** `string` (nullable): Step variant
  * **sent** `number` (nullable): Emails sent for this step
  * **opened** `number` (nullable): Emails opened for this step
  * **unique\_opened** `number` (nullable): Unique opens for this step
  * **replies** `number` (nullable): Replies for this step
  * **unique\_replies** `number` (nullable): Unique replies for this step
  * **clicks** `number` (nullable): Clicks for this step
  * **unique\_clicks** `number` (nullable): Unique clicks for this step

**Example Usage:**

```json
{
  "campaign_id": "camp_123456",
  "start_date": "2024-12-01",
  "end_date": "2024-12-31"
}
```

***

## Common Use Cases

**Lead Management:**

* Import leads with detailed qualification and assignment information
* Track lead engagement across email opens, clicks, and replies
* Manage lead lifecycle with interest status tracking
* Organize leads with custom variables for personalization

**Campaign Analytics:**

* Monitor overall campaign performance with aggregated metrics
* Track daily performance trends to optimize send timing
* Analyze step-by-step funnel performance to improve sequences
* Measure ROI with opportunity tracking and value attribution

**Data Integration:**

* Skip duplicate imports with workspace, campaign, and list filtering
* Verify leads during import to maintain email deliverability
* Use custom variables to sync with external CRM systems