API Reference

All endpoints require an API key in the Authorization header. See Authentication for details.

For transactional email endpoints (/v1/send), see Send Email.

---

Contacts

GET /api/v1/contacts

List contacts with pagination, search, and filters.

Permission: contacts:read

Query parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page, 1-100 (default: 20)
search	string	Search by email, first name, or last name
status	string	SUBSCRIBED, UNSUBSCRIBED, BOUNCED, or COMPLAINED
tag	string	Filter by tag name

Response:

POST /api/v1/contacts

Create a new contact. Checks for duplicates and suppression list.

Permission: contacts:write

Request body:

Field	Type	Required	Description
email	string	Yes	Email address
firstName	string	No	First name (max 100)
lastName	string	No	Last name (max 100)
phone	string	No	Phone number (max 30)
tags	string[]	No	Tags to assign (max 50)
customFields	object	No	Custom key-value data

Error codes: duplicate_contact (409), email_suppressed (400)

GET /api/v1/contacts/:id

Get a single contact with list and segment memberships.

Permission: contacts:read

PATCH /api/v1/contacts/:id

Update a contact's fields. Only include fields you want to change. Setting tags replaces all existing tags.

Permission: contacts:write

Field	Type	Description
firstName	string	First name
lastName	string	Last name
phone	string	Phone number
tags	string[]	Replaces all tags
status	string	SUBSCRIBED or UNSUBSCRIBED
customFields	object	Custom data

DELETE /api/v1/contacts/:id

Permanently delete a contact.

Permission: contacts:write

---

Campaigns

GET /api/v1/campaigns

List campaigns with optional status filter.

Permission: campaigns:read

Query parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page, 1-100 (default: 20)
status	string	DRAFT, SCHEDULED, SENDING, SENT, PAUSED, CANCELLED

POST /api/v1/campaigns

Create a campaign draft or schedule one. Campaigns created via API start as DRAFT (or SCHEDULED if scheduledAt is provided). The sender email must be verified.

Permission: campaigns:write

Request body:

Field	Type	Required	Description
name	string	Yes	Campaign name (max 200)
subjectLine	string	Yes	Subject line (max 998)
fromEmail	string	Yes	Verified sender email
templateId	string	No	Template to use
fromName	string	No	Sender display name
replyTo	string	No	Reply-to address
previewText	string	No	Preview text (max 200)
recipientType	string	No	all, segment, or list (default: all)
segmentId	string	No	Required when recipientType is segment
listId	string	No	Required when recipientType is list
scheduledAt	string	No	ISO datetime (must be in the future)

Error codes: sender_not_verified (400), not_found (404) for invalid template/segment/list IDs

GET /api/v1/campaigns/:id

Get a single campaign with template, segment, and list details.

Permission: campaigns:read

GET /api/v1/campaigns/:id/stats

Get full campaign analytics.

Permission: campaigns:read

Response:

---

Templates

GET /api/v1/templates

List email templates (metadata only, no HTML content).

Permission: templates:read

Query parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page, 1-100 (default: 20)
search	string	Search by name or description
category	string	Filter by template category

GET /api/v1/templates/:id

Get a single template including rendered HTML and text content.

Permission: templates:read

---

Automations

GET /api/v1/automations

List automations with optional status filter.

Permission: automations:read

Query parameters:

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Results per page, 1-100 (default: 20)
status	string	ACTIVE, PAUSED, or DRAFT

GET /api/v1/automations/:id

Get a single automation's details including trigger type, goal metrics, and performance stats.

Permission: automations:read

Response fields: id, name, description, triggerType, status, totalEntered, totalCompleted, revenueGenerated, goalType, goalConversions, goalConversionRate, goalRevenue, allowReEntry, reEntryDelayHours, createdAt, updatedAt

---

Common patterns

Pagination

All list endpoints return:

Error responses

See Error Handling for the full error code reference.