> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instantly (Cold Email)

> Connect Instantly so your Agents can add leads to campaigns, manage sending mailboxes and warmup, and route replies back into your CRM

## Overview

The [Instantly](https://instantly.ai) integration lets your agents drive a cold-email program: **add leads to campaigns** in bulk, **create and configure campaigns**, **manage sending mailboxes and warmup**, and **pull replies and campaign analytics**. An optional inbound webhook routes campaign events — replies, bounces, unsubscribes — back into Aster and your CRM as they happen.

Your organization's Instantly API key is injected automatically into every tool call — agents never see or handle the key.

## Prerequisites

* An **Instantly** account with API access
* An Instantly **API v2 key** (Instantly → Settings → Integrations → API Keys). v2 keys are scoped, so grant access to campaigns, leads, accounts, and webhooks
* An Aster **admin** to connect the integration (the connection is shared org-wide)
* A **dedicated sending domain** with warmed mailboxes. Sending cold mail from your primary business domain is what the dedicated-domain pattern exists to avoid

## Setup Guide

<Steps>
  <Step title="Get your Instantly API key">
    In Instantly, open **Settings → Integrations → API Keys** and create a key with access to campaigns, leads, accounts, and webhooks.
  </Step>

  <Step title="Connect Instantly in Aster Agents">
    Navigate to **Control Hub → Integrations**, locate the **Instantly** card, click **Connect**, and paste your API key. Aster validates it against Instantly (`GET /campaigns`) and stores it securely for your organization.

    The response includes your organization's **inbound webhook URL**. Copy it now — it contains a per-org secret that is redacted everywhere else in the product, so this is the only place it is shown. Reconnecting preserves the same URL.
  </Step>

  <Step title="Add the Instantly tool to your agent">
    Edit your agent and enable **Call Instantly API** (`instantly_api_call`).
  </Step>

  <Step title="(Optional) Route campaign events back into Aster">
    In Instantly, add a webhook pointing at the URL returned when you connected:

    ```
    https://www.asteragents.com/api/integrations/instantly/webhook?token=<your-org-webhook-token>
    ```

    Subscribe to the events you want written back. See **Inbound campaign events** below.
  </Step>
</Steps>

## Available Tools

* **Call Instantly API** (`instantly_api_call`) — any Instantly API v2 endpoint (`method` + `endpoint` + optional `body`). Instantly's API is small and uniform enough that one tool covers it.
  * `POST /leads/add` — bulk-add up to **1000** leads to a campaign. This is the add path; `POST /leads` is single-lead create.
  * `POST /campaigns` — create a campaign. `sequences` is an array but **only the first element is used**.
  * `GET /campaigns/analytics` — omit `id` for every campaign at once.
  * `GET /emails` — replies and Unibox. **Rate limited to 20 requests/minute**, unlike the rest of the API; always scope with `min_timestamp_created` rather than re-walking history.
  * `POST /accounts/warmup/enable|disable` — returns a **background job**, not a result. Poll `GET /background-jobs/:id`.

## Inbound campaign events

The webhook receiver (`api/integrations/instantly/webhook`) resolves your organization from the `token` in the URL, then writes the event back to the matching HubSpot contact.

**Written back:**

| Instantly event                                                                                | Effect                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reply_received`                                                                               | Sets `instantly_status` / `instantly_last_replied`, writes a **note** containing the reply body, and opens a **HIGH-priority task** on the contact owner |
| `auto_reply_received`, `email_bounced`, `lead_unsubscribed`, `lead_interested`, `lead_neutral` | Sets `instantly_status`                                                                                                                                  |

**Acknowledged but not written back:** `email_sent`, `email_opened`, `link_clicked`, `campaign_completed`, `account_error`. Writing a CRM property per open would spend your CRM's rate limit on a metric Instantly already reports.

### Matching events to CRM contacts

Set `hubspot_contact_id` as a **custom lead variable** when you add the lead. Instantly merges custom variables into every webhook payload, so events come back already pointing at the right contact. Without it, matching falls back to email address, which misses on aliases and plus-addressing.

### Required CRM properties

The writeback needs these contact properties to exist in your HubSpot portal first. If they are missing, every write fails.

| Property                 | Type          | Field type |
| ------------------------ | ------------- | ---------- |
| `instantly_status`       | `enumeration` | `select`   |
| `instantly_campaign_id`  | `string`      | `text`     |
| `instantly_added_date`   | `datetime`    | `date`     |
| `instantly_last_replied` | `datetime`    | `date`     |

`instantly_last_replied` must be **`datetime`**, not `date` — the webhook writes a full ISO timestamp and a `date` property rejects it.

### Failure behavior

A reply that cannot be matched to a contact returns **500** rather than being silently acknowledged, so the event is retried and the reply body is logged. A lost reply is the failure this receiver exists to prevent.