Segments API
The segments API supports saved segment definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save segments, and why preview is the safest step before using complex subscriber rules.
Manage Saved Segments
Segments define reusable subscriber logic in a workspace. A segment can represent subscribers who match tags, fields, status, engagement, import history, or other supported conditions.
Use the segments API when an external builder, migration script, reporting tool, or CRM sync needs to create or inspect subscriber rules outside the app.
Segments are definitions, not copied subscriber lists. The matching subscriber group can change when subscriber records change. Segments are useful for targeting and reporting, but preview important segment definitions before you save them or send to them.
- List existing segments before you create a new segment.
- Build the segment definition from tags, custom fields, status, forms, sequences, events, or other supported conditions.
- Call the preview endpoint before you save complex or migrated logic.
- Compare the preview count and matching subscribers with the expected counts from the source system or Mailrith app.
- Save the segment only after the definition is easy to understand and the app's
Live Previewmatches the expected subscribers. - Ask users to review important saved segments in Segments before they use those segments in live broadcasts.
- List segments when you choose subscribers for an external workflow.
- Create segments when you import reusable subscriber rules from another system.
- Update segments when the external source of truth changes the rule definition.
- Use preview before you save complex logic or before you use a segment in a high-impact campaign.
Endpoint Overview
GET /v1/segments returns saved definitions. Item endpoints let integrations inspect, update, or delete one saved segment.
POST /v1/segments saves a definition in the workspace. Use this endpoint when you want the segment to appear in Mailrith and be reused later.
POST /v1/segments/preview evaluates an unsaved definition and returns preview information. Use preview when an external builder needs to show counts before saving or when a migration needs to confirm that a rule behaves as expected. When you preview an edit to an existing segment, include current_segment_id so Mailrith can warn about circular segment references before you save.
/v1/segments List segments
Returns saved segments from the authenticated workspace.
View Schema /v1/segments Create a segment
Creates a saved segment in the authenticated workspace.
View Schema /v1/segments/{segment_id} Get a segment
Returns one saved segment from the authenticated workspace.
View Schema /v1/segments/{segment_id} Update a segment
Updates a saved segment in the authenticated workspace.
View Schema /v1/segments/{segment_id} Delete a segment
Deletes a saved segment from the authenticated workspace.
View Schema /v1/segments/preview Preview a segment definition
Returns subscriber counts for an unsaved segment definition. Include `current_segment_id` when previewing edits to an existing segment so circular segment references are rejected before saving.
View Schemacurl -X POST https://api.mailrith.com/v1/segments \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Active customers",
"description": "Imported from the previous ESP",
"definition": {
"match": "all",
"groups": []
}
}'Preview an Unsaved Definition
Preview is the safest way to test segment logic before you save the segment or use the segment in a campaign workflow. Preview lets your integration ask Mailrith which subscribers the rule would match without creating a permanent saved segment.
Use preview for external segment builders, migration validation, campaign approval tools, and AI agents that propose segment definitions. A human can review the preview count and matching subscribers before the definition becomes part of the workspace.
When your integration previews changes to an existing saved segment, send that segment's id as current_segment_id. This helps Mailrith catch loops, such as Segment A including Segment B while Segment B already includes Segment A.
- Preview before you save complex
allandanycondition groups. - Preview before you use a segment for a broadcast send.
- Include
current_segment_idwhen previewing edits to an existing saved segment. - Preview when you migrate from another platform where rule behavior may not match exactly.
- If preview results look wrong, fix the definition instead of saving the segment and editing it repeatedly.
curl -X POST https://api.mailrith.com/v1/segments/preview \
-H "Authorization: Bearer mrk_example_secret_key" \
-H "Content-Type: application/json" \
-d '{
"definition": {}
}'Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.