Skip to main content

​
Overview

The Instantly 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

1

Get your Instantly API key

In Instantly, open Settings → Integrations → API Keys and create a key with access to campaigns, leads, accounts, and webhooks.
2

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.
3

Add the Instantly tool to your agent

Edit your agent and enable Call Instantly API (instantly_api_call).
4

(Optional) Route campaign events back into Aster

In Instantly, add a webhook pointing at the URL returned when you connected:
Subscribe to the events you want written back. See Inbound campaign events below.

​
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: 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. 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.