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 email
• body (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 clients
• name (required): Internal name of the broadcast
• track_opens (optional): Whether open tracking is enabled for this broadcast
• track_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"]
  }
}