Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Segments

Saved filters over your contacts, used as broadcast audiences.

A segment is a saved group of contacts you can send a broadcast to. Create segments in the dashboard under Audience → Segments, or through the API.

There are two kinds:

  • Filter segment. It stores a filter, not a list of people. A contact who starts matching the filter is in the segment at once, and the contact count is worked out when you read it.
  • Manual segment. Created without a filter. You add and remove contacts yourself, in the dashboard or with POST /contacts/{id}/segments/{segmentId} and DELETE /contacts/{id}/segments/{segmentId}.

A filter can test a contact’s email, name, subscribe state and creation date, and any custom property. Operators include equals, contains, is set, is not set and date comparisons, and conditions combine with and/or.

Using a segment

  • Broadcasts. Choose a segment as the audience. The people who get the email are worked out when it sends, with the same filter as the count you saw before. Contacts who are unsubscribed team-wide, or who left the broadcast’s sending domain, are always left out.
  • Contacts view. Filter the list by segment. The CSV export follows the same filter.
curl -X POST "https://api.billionsend.com/segments" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trial users",
    "filter": { "match": "all", "conditions": [{ "field": "property:plan", "op": "equals", "value": "trial" }] }
  }'

GET /segments/{id} includes the live contact_count, and GET /segments/{id}/contacts lists the members. An invalid filter returns 422 and is never stored.

One segment per brand

If each of your domains is its own brand, bind a segment to the domain it belongs to by setting domain_id, when you create it or later with PATCH /segments/{id}, or by picking the domain in the dashboard.

  • A broadcast to a bound segment must be sent from that domain. From any other domain the broadcast calls return 422.
  • A segment with no domain works with every domain. "domain_id": null makes a bound segment team-wide again.
  • A domain cannot be deleted while segments are bound to it (409).

Topics can be bound the same way. Together they keep each brand’s audience, topics and opt-outs apart; see Unsubscribes.

API keys limited to a domain

An API key limited to one domain can only create segments bound to that domain, and cannot make one team-wide.

Was this page helpful?