Campaigns API
The Campaign object
A campaign is one email sent to an audience: everyone with a tag, a fixed list of contacts, or every contact with an email address.
Campaigns are draft-first, like all mail in agentlyleads. You create a campaign as a DRAFT and launch it when it is ready. Launching does not send anything: it queues one recipient per emailable, non-suppressed contact, and the send tick turns each into a draft email that a person approves in the app before it leaves.
| Field | Type | Notes |
|---|---|---|
id | string | CUID (read-only) |
name | string | Internal name |
subject | string | Email subject. {{firstName}} is replaced per recipient |
bodyHtml | string | Email body as HTML. {{firstName}} works here too |
status | string | DRAFT, SCHEDULED, SENDING, SENT, CANCELED, or OUTREACH (a container for one-to-one AI outreach drafts, never launched) |
segment | object | The audience: { type, tagId, contactIds }. type is tag, static or all |
fromEmail | string | null | The sending identity, or null for the workspace default |
offering | object | null | The product it promotes, { id, name } |
scheduledAt | string (ISO 8601) | null | When a scheduled launch runs |
recipientCount | integer | Recipients queued so far (zero until launch) |
createdAt | string (ISO 8601) | Read-only |
updatedAt | string (ISO 8601) | Read-only |
Lifecycle
| From | Action | To |
|---|---|---|
DRAFT | Launch now | SENDING |
DRAFT | Launch with scheduledAt | SCHEDULED (then SENDING when the time comes) |
DRAFT, SCHEDULED | Edit | unchanged |
DRAFT, SCHEDULED, SENDING | Cancel | CANCELED |
DRAFT | Delete | gone |
Once a campaign is SENDING it can no longer be edited. Create a new one instead.
Scopes
| Scope | Grants |
|---|---|
read:campaigns | GET /api/v1/campaigns, GET /api/v1/campaigns/{id} |
write:campaigns | Create, edit, delete, launch and cancel |
Attachments
Files that go out with every recipient email are managed through the Files API with entity: "CAMPAIGN". They can be added or removed only before the campaign sends.