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 one-time send) 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>}}.

By default, we send your broadcast as soon as you trigger it. Set scheduled_at to send it at a future time instead. You can cancel the trigger to stop a scheduled send before it starts sending. You can't change a trigger's scheduled_at value later; if you need to reschedule your broadcast, you must cancel the trigger and re-trigger the broadcast with the new timestamp.

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 automations 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.

    • expires_after
      Type: integer
      min:  
      0
      max:  
      2592000

      Number of seconds after the send starts that the broadcast should stop sending. Omit or set to 0 if you don't want the broadcast to expire. If the broadcast expires before it finishes sending, Customer.io discards the messages that haven't gone out yet instead of delivering them late. The window runs from scheduled_at when you schedule the send, and from the time we receive this request when you don't.

    • 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.

    • scheduled_at
      Type: integer
      min:  
      0
      max:  
      2147483647

      Unix timestamp (in seconds) when the broadcast will send. Omit it or set it to 0 to send right away. We reject a timestamp more than 5 minutes in the past. Scheduling also changes when we work out your audience: ids, emails, per_user_data, and data_file_url set a fixed audience when you make this request, while a recipients filter runs when the send fires.

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
{
  "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,
  "expires_after": 3600,
  "id_ignore_missing": false,
  "scheduled_at": 1796128200
}

{
  "id": 3
}

A successful request returns the trigger ID.