Campaign¶
Campaign entity. A campaign is a scheduled send of a set of payloads (Email, SMS).
The <campaign> in the URL is the numerical ID of the campaign.
Endpoints¶
| Method | URL |
|---|---|
GET |
/campaign/<campaign> |
POST |
/campaign |
PUT |
/campaign/<campaign> |
DELETE |
/campaign/<campaign> |
GET /campaign/<campaign>¶
Payload: No payload.
Returns: The campaign.
POST /campaign¶
| Parameter | Type | Description |
|---|---|---|
name |
string | Campaign name |
domain |
int | Bounce domain ID (a Domain object enabled as bouncing domain) |
list |
int | ID of the contact list targeted by the campaign |
segments[] |
int array | IDs of segments within the list. May occur more than once. If none, campaign sends to all contacts. |
state |
string | Campaign state. Valid states: DRAFT⮂SCHEDULED⮂READY⇒SENDING⇒(DONE\|ERROR) |
when |
timestamp | Scheduled send time. Unix timestamp (int) or ISO 8601 string. |
event_callback |
string | Optional. URL called back when events occur. |
Returns: The new campaign.
PUT /campaign/<campaign>¶
| Parameter | Type | Description |
|---|---|---|
name |
string | Campaign name |
domain |
int | Bounce domain ID (a Domain object enabled as bouncing domain) |
segments[] |
int array | IDs of segments within the list to target. May occur more than once. If none, campaign sends to all contacts. |
state |
string | Campaign state |
when |
timestamp | Scheduled send time |
event_callback |
string | Optional. URL called back when events occur. |
Returns: The edited campaign.
DELETE /campaign/<campaign>¶
Payload: No payload.
Returns: The deleted campaign.
Callback Behaviour¶
If an event_callback URL is defined, a POST request is executed against it whenever a
message lifecycle event occurs.
Events¶
| Event | Description |
|---|---|
submitted |
Message submitted for delivery |
delivered |
Message delivered |
bounced |
Permanent delivery failure |
opened |
Message opened |
clicked |
A link in the message was clicked |
Note
SMS payloads only generate delivered and bounced events. Email payloads generate all events.
The event_callback URL may contain a query string — those parameters are forwarded unchanged.
Callback POST parameters¶
| Parameter | Type | Description |
|---|---|---|
event |
string | Which event occurred |
when |
int | Unix timestamp of the event |
telephone[] |
string array | Phone numbers for SMS events (telephone[0], telephone[1], ...) |
email[] |
string array | Emails for email events (email[0], email[1], ...) |
Note
Events are time-aggregated. A delay of up to five minutes is expected between the actual event and the callback execution.