Subscribers and segments over the API

Most integrations do one thing: keep Broadcast’s list in step with your own app. In this lesson you add and update subscribers, run double opt-in from code, build a segment, and put people into a sequence. Use a token with Subscribers, Segments and Sequences permissions, read and write.

Create a subscriber

Post the subscriber under a subscriber key:

curl -X POST https://broadcast.example.com/api/v1/subscribers.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriber": {
      "email": "ada@example.com",
      "first_name": "Ada",
      "tags": ["newsletter"],
      "custom_data": { "plan": "pro" }
    }
  }'

Only email is required. custom_data is a JSON object for anything else you know. Segments, topics and Liquid personalization all read it.

Know three behaviours before you wire this up:

1. Posting an address that already exists is not an error. It returns 201, clears unsubscribed_at, and updates the attributes you sent. Do not call create for someone who unsubscribed unless they asked to come back.
2. The subscriber is set active, unless the address is on a suppression list. A suppressed address stays inactive, and the response carries a warning.
3. source defaults to api_subscription.

Create with double opt-in

If the person signs up on your site, let Broadcast confirm the address. Add "double_opt_in": true next to the subscriber object. Broadcast creates the subscriber with confirmed_at null, sends a confirmation email from the channel’s default confirmation template, and returns confirmation_status and confirmation_url.

Pass confirmation_template_id to use a different template. An existing confirmed subscriber is returned as it is. An existing unconfirmed one gets a fresh confirmation email.

Update a subscriber

The update endpoint does not use an id in the path. It finds the subscriber by the top-level email:

curl -X PATCH https://broadcast.example.com/api/v1/subscribers.json \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "custom_data_mode": "merge",
    "subscriber": { "custom_data": { "plan": "enterprise" } }
  }'

To change the address, put the new one in subscriber.email and keep the old one at the top level.

Tags and status

For tags, prefer the small endpoints over a full update, because they do not replace the whole list:

• POST /api/v1/subscribers/add_tag.json with email and a tags array.
• DELETE /api/v1/subscribers/remove_tag.json with the same shape.

Tags are often the cleanest bridge into automation. If a sequence uses the tag trial-started as its trigger, adding that tag from your app enrolls the person, with no other call.

For status:

• POST /api/v1/subscribers/unsubscribe.json sets unsubscribed_at and marks the subscriber inactive. Use it when someone opts out in your app.
• POST /api/v1/subscribers/deactivate.json and activate.json change the active flag that you control.

For GDPR erasure there is a redact endpoint. It removes personal data and keeps campaign statistics. It cannot be undone.

Read the list

GET /api/v1/subscribers.json takes filters: is_active, source, created_after and created_before, email (a partial match, such as gmail.com), tags[] (subscribers with all of them), and custom_data[plan]=enterprise. Results are paginated: read pagination.total_pages and ask for each page.

Build a segment in code

A segment has groups, and groups have rules, the same structure as the dashboard:

curl -X POST https://broadcast.example.com/api/v1/segments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "name": "Enterprise plan",
      "segment_groups_attributes": [{
        "match_type": "all",
        "segment_rules_attributes": [{
          "field": "custom_data.plan", "operator": "equals",
          "value": "enterprise", "rule_type": "text", "value_type": "string"
        }]
      }]
    }
  }'

Custom data fields use the custom_data. prefix, and rule_type tells Broadcast how to compare the value: text, number, date or boolean. match_type is all or any. GET /api/v1/segments/:id returns the segment with a paginated list of the subscribers who match it now. The Segments API lists every field and operator, with custom data examples for text, numbers, booleans and dates.

Enroll in a sequence

POST /api/v1/sequences/:id/add_subscriber with a subscriber object enrolls the person. If the email does not exist yet, Broadcast creates the subscriber. It returns 201 for a new enrollment, and 200 if the person was already enrolled. DELETE /api/v1/sequences/:id/remove_subscriber with email takes them out.

What you learned

• Create is idempotent on email, and it resubscribes an existing address.
• double_opt_in: true sends the confirmation email for you.
• Update finds the subscriber by top-level email. Use custom_data_mode: merge to keep other keys.
• Segments use groups of rules, and sequences take subscribers with add_subscriber.