Broadcast API
The Broadcast API allows you to programmatically create draft broadcasts. These will create broadcasts in the draft state, which you can then manually trigger through Broadcast’s own API after verifying that the broadcast is ready to send.
Required Permissions
All endpoints require authentication via an API token with appropriate permissions:
- Create broadcasts (Write)
Broadcast Object
The broadcast object contains the following fields:
Field | Description |
---|---|
`id` | The unique identifier of the broadcast |
`subject` | The subject line of the email |
`preheader` | Preview text that appears in email clients |
`body` | The content of the email |
`name` | The internal name of the broadcast |
`track_opens` | Whether open tracking is enabled for this broadcast |
`track_clicks` | Whether click tracking is enabled for this broadcast |
You will notice that several properties of broadcasts are not included in the object. At the moment, the above properties are the only ones which are exposed through this API.
Create (Draft) Broadcast
POST /api/v1/broadcasts.json
Parameters
subject
(required): Subject line of the emailbody
(required): Content of the email, which can be either a simple string or HTML. In either case, Broadcast will wrap the content in the appropriate html and body tags. If you want to incorporate an entire HTML design, just send the contents within the body tag.preheader
(recommended): Preview text that appears in email clientsname
(required): Internal name of the broadcasttrack_opens
(optional): Whether open tracking is enabled for this broadcasttrack_clicks
(optional): Whether click tracking is enabled for this broadcast
Request
curl -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"broadcast": {
"subject": "Test Subject",
"preheader": "Test Preheader",
"body": "<p>Test Body</p>",
"name": "Test Name",
"track_opens": true,
"track_clicks": true
}
}' \
http://your-domain.com/api/v1/broadcasts
Take note that the body
field should be a valid HTML string. If it is not a valid HTML string, the broadcast’s rendered body will be malformed.
When you edit a draft broadcast, the application will attempt to fix any malformed HTML, but this is not always possible.
In general, line breaks should be represented as <br>
tags, and paragraphs should be wrapped in <p>
tags. If you reference images, you must ensure that the image URL is valid.
You do not need to include the head or body tags in the body field. Broadcast will automatically wrap the content of your body during the outbound mail processing.
Response
{
"id": "123",
"subject": "Test Subject",
"preheader": "Test Preheader",
"body": "<p>Test Body</p>",
"name": "Test Name",
"track_opens": true,
"track_clicks": true,
"created_at": "2024-03-21T09:00:00Z",
"updated_at": "2024-03-21T09:00:00Z"
}
If the request is invalid, the response code will be 422 (Unprocessable Entity). The error message will be returned in the response body:
{
"errors": {
"subject": ["can't be blank"],
"body": ["can't be blank"]
}
}