# 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. - Human page: https://mailrith.com/developers/segments - Markdown page: https://mailrith.com/developers/segments.md - Category: API Resources - Reading time: 6 min read - Last updated: 2026-07-13 - Related keywords: Segments API, Segments API developer docs, API Resources, API Resources developer docs, Mailrith developer docs, Mailrith public API, Manage Saved Segments, Endpoint Overview, Preview an Unsaved Definition, Subscribers API, Tags API, API Reference ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What this guide covers Manage saved subscriber rules and preview unsaved segment definitions before saving or sending. ## 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. 1. List existing segments before you create a new segment. 2. Build the segment definition from tags, custom fields, status, forms, sequences, events, or other supported conditions. 3. Call the preview endpoint before you save complex or migrated logic. 4. Compare the preview count and matching subscribers with the expected counts from the source system or Mailrith app. 5. Save the segment only after the definition is easy to understand and the app's `Live Preview` matches the expected subscribers. 6. Ask users to review important saved segments in [Segments](https://mailrith.com/docs/segments.md) 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. Related OpenAPI operation groups: - Segments **Create a Segment** ```bash curl -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 `all` and `any` condition groups. - Preview before you use a segment for a broadcast send. - Include `current_segment_id` when 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. **Preview Request** ```bash curl -X POST https://api.mailrith.com/v1/segments/preview \ -H "Authorization: Bearer mrk_example_secret_key" \ -H "Content-Type: application/json" \ -d '{ "definition": {} }' ``` ## Related Guides - [Subscribers API](https://mailrith.com/developers/subscribers.md): The subscribers resource is the main way integrations write Subscriber data in `v1`. This guide explains when to list subscribers, when to upsert subscribers, how Mailrith chooses the workspace, what to include in an upsert body, and when to use async imports instead of many single requests. - [Tags API](https://mailrith.com/developers/tags.md): The tags API gives integrations a lightweight way to manage subscriber labels. This guide explains when to use tags, when to use custom fields instead, how to list or create tags, and how to name tags so workspace users understand each label. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.