Customer.io
v1.0.0
OpenAPI 3.1.0

Send an API-triggered broadcast

US region

Client Libraries
Shell Curl

Send an API-triggered broadcast

​

Trigger a broadcast (not a newsletter) and optionally provide data to populate liquid placeholders in the message.

The shape of the request depends on how you define your audience: default (the recipients set in the UI), custom filter conditions, a list of emails, a list of customer IDs, a map of users, or a data file.

You can only trigger broadcasts to send to people you've already added to your workspace. A broadcast cannot add or identify new people. If you reference people who don't exist in your broadcast audience, the broadcast will fail by default. You can override this behavior by setting the email_ignore_missing and/or id_ignore_missing flags to true. The broadcast will skip over any people who don't exist in your workspace and send to the remaining recipients.

You can reference properties in the data object in your broadcast using liquid—{{trigger.<property_in_data_obj>}}.

If your broadcast produces a 422 error, you can get more information about the errors to see what went wrong.

This endpoint is rate-limited to one request every 10 seconds. After exceeding this, you'll receive a status of 429. Learn more about API-triggered broadcast limits above.

Broadcasts are optimized to send messages to a large audience and not for one-to-one interactions. Use our transactional API or event-triggered campaigns to respond to your audience on an individual, one-to-one basis.

Path Parameters
  • broadcast_id
    Type: integer
    required

    The ID of the broadcast that you want to trigger.

Body
application/json

  • Send your broadcast to the default set of recipients defined in the UI.

    • data
      Type: object

      Contains information you want to use to populate your broadcast.

    • email_add_duplicates
      Type: boolean

      an email address associated with more than one profile id is an error.

    • email_ignore_missing
      Type: boolean

      If false, a missing email causes the broadcast to error and fail. If true, the broadcast will skip over any people in your audience who don't have emails, and continue sending to the rest of your audience.

    • id_ignore_missing
      Type: boolean

      If false, a missing customer ID causes the broadcast to error and fail. If true, the broadcast will skip over any people in your audience who don't have IDs, and continue sending to the rest of your audience.

Responses
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

  • 404

    The broadcast_id does not exist.

  • application/json
Request Example for post/v1/campaigns/{broadcast_id}/triggers
curl https://api.customer.io/v1/campaigns/1/triggers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "data": {
    "headline": "Roadrunner spotted in Albuquerque!",
    "date": 1511315635,
    "text": "We received reports of a roadrunner in your immediate area! Head to your dashboard to view more information!"
  },
  "email_add_duplicates": false,
  "email_ignore_missing": false,
  "id_ignore_missing": false
}'

{
  "id": 3
}

A successful request returns the trigger ID.