# Segments API



> The segments surface supports saved subscriber definitions, imported subscriber rules, and previews for unsaved logic. This guide explains how segments behave, when to save them, and why preview is the safest step before using complex subscriber rules.



- Human page: https://mailrith.com/developers/segments

- Category: API Resources

- Reading time: 6 min read



## 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 people 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 subscriber group can change as subscribers change. That makes segments useful for targeting and reporting, but preview important definitions before saving or sending to them.

1. List existing segments before creating a new one.
2. Build the segment definition from tags, custom fields, status, forms, sequences, events, or other supported conditions.
3. Call the preview endpoint before saving complex or migrated logic.
4. Compare the preview result with expected counts from the source system or Mailrith app.
5. Save the segment only after the definition is understandable 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 using them in live broadcasts.

- List segments when choosing subscribers for an external workflow.
- Create segments when importing reusable subscriber rules from another system.
- Update segments when the external source of truth changes the rule definition.
- Use preview before saving complex logic or before using 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` persists a definition in the workspace. Use it 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 wants to show counts before saving or when a migration wants to confirm a rule behaves as expected.

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 saving it or using it in a campaign workflow. It lets your integration ask Mailrith what 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 subscriber definitions. A human can review the preview result before the definition becomes part of the workspace.

- Preview before saving complex `all` and `any` condition groups.
- Preview before using a segment for a broadcast send.
- Preview when migrating from another platform where rule behavior may not match exactly.
- If preview results look wrong, fix the definition rather than saving and editing 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 core subscriber write surface in `v1`. This guide explains when to list, when to upsert, 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 surface gives integrations a lightweight way to manage subscriber labels. This guide explains when tags are the right choice, when custom fields are better, how to list or create tags, and how to name tags so real workspace users understand them.

- [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 it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.