API Documentation

Automate cold email outreach with Heyo Email's high-speed REST API. Programmatically upload leads, start sequence campaigns, monitor inbox warmup, and read prospect replies with AI sentiment categorization.

Log into your Heyo account to automatically populate code examples with your live API keys.Log In

Overview & Base URL

The Heyo Email REST API follows standard REST conventions with resource-oriented URLs, JSON request/response payloads, and HTTP status codes.

Base URL:https://app.heyoemail.com/api/v1

Authentication

Bearer Auth

All API requests must include your secret API key in the Authorization header as a Bearer token.

Authorization: Bearer hy_live_YOUR_SECRET_KEY

Lead Variables & Template Personalization

Heyo Email dynamically merges lead data and sender identities into your campaign sequences at send time. Ingest any of the following parameters with your leads:

API Payload Field	Sequence Tag	Fallback Default	Description
firstName	{{firstName}}	"there"	Prospect's given name.
lastName	{{lastName}}	"" (blank)	Prospect's surname.
company	{{company}}	"your company"	Prospect's company or organization.
(Mailbox Sender)	{{sender_first_name}}	Inbox first name	Sender first name of the assigned mailbox.
(Mailbox Sender)	{{sender_last_name}}	Inbox last name	Sender surname of the assigned mailbox.
(System Unsubscribe)	{{unsubscribe}}	HMAC-signed link	Custom domain 1-click unsubscribe link.
(Spintax)	{Hi\|Hello\|Hey}	Random variation	Spintax variations randomized per email sent.

Rate Limits & Batch Caps

Standard Rate

120 req/min

Per secret API key.

Bulk Lead Ingest

500 leads/req

Max batch size per bulk call.

Active Contact Tier

200,000 leads

Based on your active plan tier.

POST

/api/v1/leads

Single Lead Ingest

Creates or updates a single prospect. Automatically filters against your workspace Global DNC suppression list, and optionally attaches the lead to a campaign or lead list.

Request Body (JSON)

Field	Type	Required	Description
email	string	Yes	Email address of the prospect.
firstName	string	Optional	First name for sequence personalization (`{{firstName}}`).
lastName	string	Optional	Last name for personalization (`{{lastName}}`).
company	string	Optional	Company name (`{{company}}`).
campaignId	string	Optional	Campaign ID to automatically enroll the prospect into.
leadListId	string	Optional	Lead List ID to group the contact into.

curl -X POST https://app.heyoemail.com/api/v1/leads \
  -H "Authorization: Bearer hy_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sarah.connor@cyberdyne.com",
    "firstName": "Sarah",
    "lastName": "Connor",
    "company": "Cyberdyne Systems",
    "campaignId": "cm123456"
  }'

POST

/api/v1/leads/bulk

Max 500 Leads / Request

Batch import up to 500 leads per request with automated DNC domain & email suppression. Ideal for integrations with Heyo Infra, your CRM, or custom data workflows.

curl -X POST https://app.heyoemail.com/api/v1/leads/bulk \
  -H "Authorization: Bearer hy_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { "email": "elena@startup.io", "firstName": "Elena", "lastName": "Rostova", "company": "Startup IO" },
      { "email": "marcus@enterprise.com", "firstName": "Marcus", "lastName": "Vance", "company": "Enterprise Global" }
    ],
    "campaignId": "cm123456"
  }'

GET & PATCH

/api/v1/campaigns

Campaign Sequences

List campaign metrics, sequence step breakdowns, and programmatically pause or activate sequence dispatching.

# Pause or Activate a campaign
curl -X PATCH https://app.heyoemail.com/api/v1/campaigns/cm123456 \
  -H "Authorization: Bearer hy_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

GET

/api/v1/unibox/threads

AI Sentiment Analyzed

Fetch incoming prospect replies across all your inboxes with AI sentiment categorization (POSITIVE, NEGATIVE_OPTOUT, UNDELIVERABLE, OUT_OF_OFFICE).

curl -X GET "https://app.heyoemail.com/api/v1/unibox/threads?sentiment=POSITIVE&limit=10" \
  -H "Authorization: Bearer hy_live_YOUR_SECRET_KEY"

POST

/api/v1/unibox/reply

Send Prospect Reply

Send a response to an ongoing prospect conversation thread via the assigned Microsoft Exchange account.

curl -X POST https://app.heyoemail.com/api/v1/unibox/reply \
  -H "Authorization: Bearer hy_live_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "th_123456",
    "messageBody": "Hi Sarah, happy to share our product demo! Here is our calendar link: calendly.com/team"
  }'

Error Handling & Status Codes

When an error occurs, the API returns standard HTTP status codes and a JSON error message:

HTTP Status	Error Code	Description
401 Unauthorized	INVALID_API_KEY	Missing, malformed, or revoked secret API token.
403 Forbidden	GROWTH_PLAN_REQUIRED	Workspace is on Free or Starter tier. Upgrade to Growth ($79/mo) required.
400 Bad Request	BATCH_SIZE_EXCEEDED	Bulk lead ingest payload exceeded the 500 leads cap.
409 Conflict	DNC_SUPPRESSED	Lead email address exists on your workspace DNC list.