Campaigns API
Create, edit and delete campaigns
All three need the write:campaigns scope.
POST /api/v1/campaigns
Creates a DRAFT. Nothing is queued or sent.
POST /api/v1/campaigns HTTP/1.1
Host: agentlyleads.com
Authorization: Bearer alk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
{
"name": "Spring restock",
"subject": "Restocking for spring, {{firstName}}?",
"bodyHtml": "<p>Hi {{firstName}},</p><p>We have lick salt back in stock. Want me to hold a pallet for you?</p><p>Kevin</p>",
"segmentType": "tag",
"tagName": "Farms",
"offeringId": "cmq2offr0alk34567890"
}| Field | Required | Notes |
|---|---|---|
name | yes | Up to 200 characters |
subject | yes | Up to 500 characters |
bodyHtml | yes | HTML. {{firstName}} is replaced per recipient |
segmentType | yes | tag, static or all |
tagId or tagName | for tag | The tag by ID, or by name (case-insensitive) |
contactIds | for static | Up to 5000 contact IDs. Every one must be in your workspace; unknown IDs are listed back in a 404 |
fromEmail | no | A verified sending identity. See GET /api/v1/emails/identities |
offeringId | no | The product this campaign promotes |
asUserEmail | no | The workspace member recorded as the creator. Defaults to the workspace owner |
Returns 201 with { "campaign": { ... } }.
PATCH /api/v1/campaigns/{id}
Revises a DRAFT or SCHEDULED campaign. Only the fields you send change. To change the audience, send segmentType with tagId, tagName or contactIds as above. offeringId: null unlinks the product; fromEmail: null goes back to the workspace default.
A campaign that is SENDING, SENT or CANCELED is locked and returns 409.
PATCH /api/v1/campaigns/cmq2camp0alk34567890 HTTP/1.1
Content-Type: application/json
{ "subject": "Spring restock: pallets available" }DELETE /api/v1/campaigns/{id}
Permanently deletes a DRAFT that was never launched, with its attachments. Any other status returns 409: a campaign that has been launched carries history, so cancel it instead.
{ "deleted": 1, "id": "cmq2camp0alk34567890" }