Campaigns
The Campaigns resource has full CRUD functionality. It allows you to Create, Retrieve, Edit and Delete Campaigns. The following actions can be performed on this resource...
Retrieve All Campaigns
Retrieves all campaigns for a specific brand.
You can include additional parameters in the request as described in the Query Parameters section. For instance, the request below will return campaigns with a status of "sent".
Example Response:
{
"data": [
{
"campaign_id": 3333,
"_brand_id":123456789,
"_created_by_user_id": 6,
"name": "Welcome",
"body": “Welcome to ACME,
"media_url": “https://mediaurl”,
"status": "sent",
"status_detail": null,
"status_date": "2024-01-01 16:23:23",
"completion_percentage": 100,
"created": "2024-01-01 16:23:44",
"scheduled": null,
"started": "2024-01-01 16:23:44",
"finished": "2024-01-01 16:24:15",
"last_Editd": "2024-01-01 16:21:35"
"audience": [
{
"campaign_audience_id": 112,
"_campaign_id": 3333,
"all_contacts": 0,
"_contact_list_id": 21,
"_segment_id": null,
"size": 2000,
"created": "2024-01-01 10:43:53"
}
]
}
],
"pagingData": {
"prevPage": null,
"currentPage": null,
"nextPage": null,
"currentPageString": null,
"hasMore": false
}
}
Retrieve a Specific Campaign
Retrieves a single campaign with the campaign ID equal to {id}. The campaign ID can be found using the retrieve all campaigns endpoint.
Example Response:
{
"campaign_id": 3333,
"_brand_id": 123456789,
"_created_by_user_id": null,
"name": "Send From API",
"body": "Welcome to ACME",
"media_url": null,
"audience_size": 107,
"status": "sent",
"status_detail": null,
"status_date": "2024-12-05 20:27:22",
"completion_percentage": 32,
"created": "2024-12-05 20:27:20",
"scheduled": "2024-12-31 10:00:00",
"started": "2024-12-05 20:27:20",
"finished": "2024-12-05 20:27:22",
"last_updated": "2024-12-05 20:27:22",
"audience": [
{
"campaign_audience_id": 119,
"_campaign_id": 3333,
"all_contacts": 0,
"_contact_list_id": null,
"_segment_id": 25,
"size": 107,
"created": "2024-12-05 20:27:20"
}
]
}
Edit a Specific Unsent Campaign
Allows you to Edit existing campaigns. You can target an existing contact by passing the campaign ID in your PUT request. The campaign ID can be found using the retrieve all campaigns endpoint.
Campaigns can only be edited if they are in an unsent state (scheduled, draft).
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| name | Name of campaign |
| body | Message that you are sending |
| media_url | URL of media you are including in campaign |
| status | Change status to draft, scheduled, or send. |
| scheduled | Date/time the message is to be sent, ignored if status is “send” |
| audience[all] | Array of lists/segments the message will be sent to. Use [all] to send to all contacts. |
Example Request Body
{
"name": "Edit Campaign from API",
"body": "Welcome to ACME",
"media_url": null,
"status": "draft",
"scheduled": "2024-12-31 10:00:00",
"audience": {
"segments": [25],
"contact_lists": [21]
}
}
Example Response:
{
"campaign_id": 3333,
"_brand_id": 123456789,
"_created_by_user_id": null,
"name": "Edit Campaign from API",
"body": "Welcome to ACME",
"media_url": null,
"audience_size": 107,
"status": "draft",
"status_detail": null,
"status_date": "2024-12-05 18:23:12",
"completion_percentage": null,
"created": "2024-12-05 18:21:06",
"scheduled": "2024-12-31 10:00:00",
"started": null,
"finished": null,
"last_updated": "2024-12-05 18:23:12",
"audience": [
{
"campaign_audience_id": 119,
"_campaign_id": 3333,
"all_contacts": 0,
"_contact_list_id": 21,
"_segment_id": 25,
"size": 107,
"created": "2024-12-05 18:21:06"
}
]
}
Create a Campaign
Creates a campaign. You can specify whether the campaign is to be sent immediately, scheduled for future delivery, or saved as a draft.
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| name | Name of campaign |
| body | Message that you are sending |
| media_url | URL of media you are including in campaign |
| status |
Indicates timing of send. There are three options:
|
| scheduled | Date/time the message is to be sent, ignored if status is “send” |
| audience[all] | Array of lists/segments the message will be sent to. Use [all] to send to all contacts. |
Example Request Body
{
"name": "Send From API",
"body": "Welcome to ACME",
"media_url": null,
"status": "send",
"scheduled": "2024-12-31 10:00:00",
"audience": {
"segments": [25],
"contact_lists": [21]
}
}
Example Response:
{
"_brand_id": 123456789,
"_created_by_user_id": null,
"name": "Send from API",
"body": "Welcome to ACME",
"media_url": null,
"status": "queued",
"scheduled": "2024-12-31 10:00:00",
"status_date": "2024-12-05 20:22:30",
"status_detail": "This campaign is queued for send.",
"campaign_id": 110,
"created": "2024-12-05 20:22:30",
"last_updated": "2024-12-05 20:22:30",
"audience": [
{
"_campaign_id": 3333,
"all_contacts": 0,
"_contact_list_id": 25,
"_segment_id": 21,
"campaign_audience_id": 116,
"created": "2024-12-05 20:22:30"
}
]
}
Delete a Specific Campaign
Deletes an existing campaign with the campaign ID equal to {id}. The campaign ID can be found using the retrieve all campaigns endpoint. Using this action, the campaign is simply removed completely from the brand. The campaign cannot be deleted if the campaign has been sent—only a campaign in an unsent state (scheduled, draft) can be deleted.
Example Response:
[]