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}andDELETE /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": nullmakes 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.