API Reference

The reference below covers every endpoint in the Campaigns API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

GET/api/v1/campaigns

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

status?string

Campaign status.

Value in

"DRAFT"
"SCHEDULED"
"SENDING"
"SENT"
"CANCELED"
"OUTREACH"

offeringId?string

Only campaigns promoting this product.

q?string

Matches the name or subject.

updatedSince?string

Only records updated at or after this moment.

Formatdate-time

limit?integer

Range1 <= value <= 1000

Default100

cursor?string

The nextCursor from the previous page.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/campaigns"

{  "campaigns": [    {      "id": "string",      "name": "string",      "subject": "string",      "bodyHtml": "string",      "status": "DRAFT",      "segment": {        "type": "tag",        "tagId": "string",        "contactIds": [          "string"        ]      },      "fromEmail": "string",      "offering": {        "id": "cmq2comp0alk34567890",        "name": "Acme Corp"      },      "scheduledAt": "2019-08-24T14:15:22Z",      "recipientCount": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "nextCursor": "string"}

{  "error": "status must be one of: DRAFT, SCHEDULED, SENDING, SENT, CANCELED, OUTREACH."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:campaigns."}

{  "error": "Rate limit exceeded."}

POST/api/v1/campaigns

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Lengthlength <= 200

subject*string

Lengthlength <= 500

bodyHtml*string

segmentType*string

Value in

"tag"
"static"
"all"

tagId?string

tagName?string

Case-insensitive.

contactIds?array<string>

Itemsitems <= 5000

fromEmail?string

offeringId?string

asUserEmail?string

Formatemail

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/campaigns" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "subject": "string",    "bodyHtml": "string",    "segmentType": "tag"  }'

{  "campaign": {    "id": "string",    "name": "string",    "subject": "string",    "bodyHtml": "string",    "status": "DRAFT",    "segment": {      "type": "tag",      "tagId": "string",      "contactIds": [        "string"      ]    },    "fromEmail": "string",    "offering": {      "id": "cmq2comp0alk34567890",      "name": "Acme Corp"    },    "scheduledAt": "2019-08-24T14:15:22Z",    "recipientCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "Pass contactIds when segmentType is 'static'."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:campaigns."}

{  "error": "No tag named \"Farms\"."}

{  "error": "Rate limit exceeded."}

GET/api/v1/campaigns/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The agentlyleads ID.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/campaigns/string"

{  "campaign": {    "id": "string",    "name": "string",    "subject": "string",    "bodyHtml": "string",    "status": "DRAFT",    "segment": {      "type": "tag",      "tagId": "string",      "contactIds": [        "string"      ]    },    "fromEmail": "string",    "offering": {      "id": "cmq2comp0alk34567890",      "name": "Acme Corp"    },    "scheduledAt": "2019-08-24T14:15:22Z",    "recipientCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "analytics": {    "totalRecipients": 0,    "sentRecipients": 0,    "skippedRecipients": 0,    "failedRecipients": 0,    "delivered": 0,    "opens": 0,    "machineOpens": 0,    "clicks": 0,    "bounces": 0,    "unsubscribes": 0,    "complaints": 0,    "replies": 0,    "positiveReplies": 0  }}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:campaigns."}

{  "error": "Campaign not found."}

{  "error": "Rate limit exceeded."}

PATCH/api/v1/campaigns/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The agentlyleads ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Lengthlength <= 200

subject?string

Lengthlength <= 500

bodyHtml?string

segmentType?string

Value in

"tag"
"static"
"all"

tagId?string

tagName?string

contactIds?array<string>

Itemsitems <= 5000

fromEmail?string|null

offeringId?string|null

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/campaigns/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "campaign": {    "id": "string",    "name": "string",    "subject": "string",    "bodyHtml": "string",    "status": "DRAFT",    "segment": {      "type": "tag",      "tagId": "string",      "contactIds": [        "string"      ]    },    "fromEmail": "string",    "offering": {      "id": "cmq2comp0alk34567890",      "name": "Acme Corp"    },    "scheduledAt": "2019-08-24T14:15:22Z",    "recipientCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "Pass at least one field to change."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:campaigns."}

{  "error": "Campaign not found."}

{  "error": "This campaign is SENDING and can no longer be edited. Create a new campaign instead."}

{  "error": "Rate limit exceeded."}

DELETE/api/v1/campaigns/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The agentlyleads ID.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/campaigns/string"

{  "deleted": 1,  "id": "string"}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:campaigns."}

{  "error": "Campaign not found."}

{  "error": "Only DRAFT campaigns can be deleted."}

{  "error": "Rate limit exceeded."}

POST/api/v1/campaigns/{id}/launch

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The agentlyleads ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scheduledAt?|

Omit to launch now.

Formatdate-time

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/campaigns/string/launch" \  -H "Content-Type: application/json" \  -d '{}'

{  "campaign": {    "id": "string",    "name": "string",    "subject": "string",    "bodyHtml": "string",    "status": "DRAFT",    "segment": {      "type": "tag",      "tagId": "string",      "contactIds": [        "string"      ]    },    "fromEmail": "string",    "offering": {      "id": "cmq2comp0alk34567890",      "name": "Acme Corp"    },    "scheduledAt": "2019-08-24T14:15:22Z",    "recipientCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  },  "queuedRecipients": 0}

{  "error": "This campaign's audience has no contacts with an email address."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:campaigns."}

{  "error": "Campaign not found."}

{  "error": "This campaign is SENT and cannot be launched. Only DRAFT or SCHEDULED campaigns can."}

{  "error": "Rate limit exceeded."}

POST/api/v1/campaigns/{id}/cancel

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The agentlyleads ID.

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/campaigns/string/cancel"

{  "campaign": {    "id": "string",    "name": "string",    "subject": "string",    "bodyHtml": "string",    "status": "DRAFT",    "segment": {      "type": "tag",      "tagId": "string",      "contactIds": [        "string"      ]    },    "fromEmail": "string",    "offering": {      "id": "cmq2comp0alk34567890",      "name": "Acme Corp"    },    "scheduledAt": "2019-08-24T14:15:22Z",    "recipientCount": 0,    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:campaigns."}

{  "error": "Campaign not found."}

{  "error": "This campaign is SENT and cannot be cancelled."}

{  "error": "Rate limit exceeded."}

API Reference

200application/json

400application/json

401application/json

403application/json

429application/json

201application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

200application/json

401application/json

403application/json

404application/json

409application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

200application/json

401application/json

403application/json

404application/json

409application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`