Segments

A segment is a named list of contacts. Every broadcast is sent to exactly one segment, so you create a segment before you can send marketing email.

A segment holds a fixed set of members that you add and remove yourself. It does not filter contacts automatically by property or behavior. A contact can be in any number of segments, and removing a contact from a segment does not delete the contact.

Create a segment

In the dashboard, open Audience, choose Segments and create one. With the API, use a full_access key:

curl -X POST https://api.sooner.dev/segments \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter subscribers" }'

{ "object": "segment", "id": "jd5f2h8k4m7p1r6t9v3x0z2c", "name": "Newsletter subscribers" }

The name is 1 to 100 characters. Names do not have to be unique.

Add and remove members

There are three ways to put a contact in a segment.

When you create the contact, pass segments:

{ "email": "ada@example.com", "segments": [{ "id": "jd5f2h8k4m7p1r6t9v3x0z2c" }] }

For an existing contact, add it by contact ID or email:

curl -X POST https://api.sooner.dev/contacts/ada@example.com/segments/jd5f2h8k4m7p1r6t9v3x0z2c \
  -H "Authorization: Bearer $SOONER_API_KEY"

{ "id": "jd5f2h8k4m7p1r6t9v3x0z2c" }

Through the segment, create a contact directly inside it with POST /segments/{id}/contacts. The contact is added to that segment, and any segments field in the body is ignored.

To remove a contact from a segment and keep the contact:

curl -X DELETE https://api.sooner.dev/contacts/ada@example.com/segments/jd5f2h8k4m7p1r6t9v3x0z2c \
  -H "Authorization: Bearer $SOONER_API_KEY"

{ "id": "jd5f2h8k4m7p1r6t9v3x0z2c", "deleted": true }

List a segment's contacts

curl "https://api.sooner.dev/segments/jd5f2h8k4m7p1r6t9v3x0z2c/contacts?limit=50" \
  -H "Authorization: Bearer $SOONER_API_KEY"

The response is a paginated list of contacts, newest member first. See Pagination.

Delete a segment

DELETE /segments/{id} deletes the segment and its memberships. The contacts stay in your project. Deleting happens in the background, so a very large segment can take a moment to disappear completely. Point any draft broadcast that used it at another segment before you send. In the dashboard, deleting a segment needs the admin role.

Segments and sending

When a broadcast starts sending, Sooner reads the segment's members at that moment. Contacts you add before sending starts are included, and contacts that are unsubscribed, opted out of the broadcast's topic, or suppressed are skipped. See Broadcasts.

The audiences paths

Older Resend code calls segments "audiences". The paths /audiences and /audiences/{id}/contacts return the same data as /segments, with object set to audience. New code should use /segments.

See the segments API reference for every endpoint.