> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Segments

> Build dynamic contact groups defined by conditions that update automatically as contact data and subscriptions change

A segment is a dynamic group of contacts defined by conditions. Unlike a [list](/learn/audience/lists) — which is static and only changes when you add or remove contacts manually — a segment continuously matches contacts based on their data. When a contact's status, properties, list memberships, or topic subscriptions change, segment membership updates automatically.

Segments are how you target specific slices of your audience for campaigns. Common examples:

* "Subscribed contacts whose `plan` equals `pro`"
* "Contacts who joined after October 1st and are subscribed to the Weekly Digest topic"
* "Contacts on the 'Beta Users' list whose email ends with `@acme.com`"

## How Segments Work

A segment is made up of **condition groups**. Each group contains one or more conditions, and a contact must satisfy every group to be included. Within a single group, the conditions are combined with **OR** — any one match is enough. Between groups, the logic is **AND** — all groups must match.

In plain English:

> **(condition A OR condition B)** AND **(condition C OR condition D)**

This structure lets you express expressive queries without writing SQL. For example, "subscribed contacts (group 1: status = subscribed) who are either VIPs or have placed more than 10 orders (group 2: plan = vip OR order\_count > 10)".

<Note>
  Segments can also be managed programmatically. The [Audience Segments API](/api-reference/audience/list-audience-segments) lets you create, update, and delete segments and their conditions from your own application.
</Note>

## Creating a Segment

<Steps>
  <Step title="Open the Segments page">
    Go to **Audience** → **Segments** and click **Create segment**.
  </Step>

  <Step title="Name your segment">
    Use a name that explains what the segment represents (for example, "Pro plan, active in last 30 days"). Segment names must be unique within your team.
  </Step>

  <Step title="Optionally scope to a list">
    If you want the segment to only consider contacts from a specific list, choose that list. Otherwise the segment runs over your entire audience.
  </Step>

  <Step title="Add condition groups">
    Pick a field, an operator, and a value. Add additional conditions to the same group (OR), or add a new group (AND). You can mix conditions across different field types in the same segment.
  </Step>

  <Step title="Preview the match count">
    The live preview panel shows the contacts that match your current conditions as you build, and the total matching count. Adjust until you're satisfied.
  </Step>

  <Step title="Save">
    Save the segment. The contact count is cached and refreshed in the background as your audience changes.
  </Step>
</Steps>

<Card title="Try it in the app" icon="wand-magic-sparkles" href="https://app.lettr.com/audience/segments?guide=eyJ2IjoxLCJzdGVwcyI6W3siYW5jaG9yIjoiYXVkaWVuY2Uuc2VnbWVudHMuY3JlYXRlIiwibWVzc2FnZSI6IkNyZWF0ZSBhIHNlZ21lbnQgdG8gdGFyZ2V0IGNvbnRhY3RzIGR5bmFtaWNhbGx5IGJ5IGNvbmRpdGlvbnMgdGhhdCB1cGRhdGUgYXMgeW91ciBkYXRhIGNoYW5nZXMuIn0seyJhbmNob3IiOiJhdWRpZW5jZS5zZWdtZW50cy5uYW1lLWlucHV0IiwibWVzc2FnZSI6Ik5hbWUgdGhlIHNlZ21lbnQgZm9yIHdoYXQgaXQgcmVwcmVzZW50cywgZS5nLiBQcm8gcGxhbiBhY3RpdmUgaW4gbGFzdCAzMCBkYXlzLiBOYW1lcyBtdXN0IGJlIHVuaXF1ZS4ifSx7ImFuY2hvciI6ImF1ZGllbmNlLnNlZ21lbnRzLnN0YXJ0IiwibWVzc2FnZSI6IlN0YXJ0IGJ1aWxkaW5nLiBUaGUgY29uZGl0aW9uIGdyb3VwcyBhbmQgdGhlIGxpdmUgbWF0Y2gtY291bnQgcHJldmlldyBvcGVuIG5leHQuIn1dLCJkb2NzIjoiaHR0cHM6Ly9kb2NzLmxldHRyLmNvbS9sZWFybi9hdWRpZW5jZS9zZWdtZW50cyJ9">
  Follow an interactive walkthrough of this guide inside Lettr.
</Card>

## Fields You Can Filter By

The segment builder exposes every piece of contact data Lettr stores:

| Field               | What it represents                                                                             |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| `email`             | The contact's email address                                                                    |
| `status`            | One of `subscribed`, `unsubscribed`, `bounced`, `complained`, `unverified`                     |
| `created_at`        | When the contact was added to your audience                                                    |
| `topics`            | Whether the contact is subscribed to a specific topic                                          |
| `lists`             | Whether the contact is a member of a specific list                                             |
| `properties.{name}` | Any [custom property](/learn/audience/contacts#custom-properties) you've defined for your team |

Custom properties appear in the field picker by name. Each property uses operators appropriate for its type (string, number, boolean, date, or JSON).

## Operators

Each condition uses an operator that depends on the field type. Lettr supports the following:

| Operator                | Description                             | Field types                         |
| ----------------------- | --------------------------------------- | ----------------------------------- |
| `contains`              | Value contains the substring            | String                              |
| `not_contains`          | Value does not contain the substring    | String                              |
| `equals`                | Value matches exactly                   | String, Number, Status, Topic, List |
| `not_equals`            | Value does not match                    | String, Number, Status, Topic, List |
| `starts_with`           | Value begins with the substring         | String                              |
| `not_starts_with`       | Value does not begin with the substring | String                              |
| `ends_with`             | Value ends with the substring           | String                              |
| `not_ends_with`         | Value does not end with the substring   | String                              |
| `is_true`               | Boolean value is `true`                 | Boolean                             |
| `is_false`              | Boolean value is `false`                | Boolean                             |
| `greater_than`          | Numeric value is greater                | Number                              |
| `greater_than_or_equal` | Numeric value is greater or equal       | Number                              |
| `less_than`             | Numeric value is less                   | Number                              |
| `less_than_or_equal`    | Numeric value is less or equal          | Number                              |
| `before`                | Date is earlier than the given date     | Date                                |
| `after`                 | Date is later than the given date       | Date                                |

For `topics` and `lists` fields, `equals` means "is a member" and `not_equals` means "is not a member".

## AI Segment Builder

Building conditions by hand is fine for simple segments, but for complex ones you can describe the audience in plain English and let Lettr's AI generate the conditions for you.

In the **Create segment** form, click the AI prompt option and type something like:

> "Subscribed contacts on the Pro plan who signed up after October 1st and aren't already on the Weekly Digest topic."

The AI converts your description into structured condition groups, opens the segment editor with them pre-filled, and lets you review or adjust before saving.

<Tip>
  The AI works best when you reference your custom properties and topics by their actual names. If your property is called `plan`, say "plan equals pro" rather than "pro tier customers" — it removes ambiguity.
</Tip>

## List-Scoped Segments

A segment can optionally be scoped to a single [list](/learn/audience/lists). When scoped, the segment only matches contacts who are members of that list **and** satisfy the conditions.

List-scoped segments are useful when you want to slice a specific list further without affecting the rest of your audience. For example, a list called "Onboarding Cohort October 2026" can have its own segments for "completed the welcome tour" or "didn't open the first email" — without those segments running over your entire audience.

## Renaming Lists and Topics

This is the most common gotcha with segments:

<Warning>
  Segments reference lists and topics by their **name** (the actual string) rather than by an internal ID. If you rename a list or a topic, every segment that uses it in a condition will silently stop matching against it — the segment will keep working but will look at the old name, which no longer exists.

  When you rename a list or topic, search your segments for any conditions that referenced the old name and update them.
</Warning>

Renaming a *segment* itself is safe — campaigns reference segments by their internal ID, so a segment rename doesn't break anything.

## Match Counts and Refresh

Each segment shows its current match count on the Segments page. Counts are cached and refreshed asynchronously when your audience changes — large audiences are not recounted on every page load. If you've just made a change you want to verify (for example, you imported a thousand contacts that should match a segment), give it a moment for the count to settle, or use the segment's preview to query live.

## Using Segments in Campaigns

When you build a [campaign](/learn/campaigns/introduction), you can target one or more segments in its audience selection step. The campaign sends to the union of all selected segments' contacts (with `subscribed` status). The segment is evaluated at the moment recipients are being prepared for the send — so a campaign always reflects the audience as it stands when you send it, not when you originally created the segment.

A contact who matches multiple selected segments still only receives the email once.

## Next Steps

<CardGroup cols={2}>
  <Card title="Contacts" icon="user" href="/learn/audience/contacts">
    Set up custom properties to filter on
  </Card>

  <Card title="Lists" icon="layer-group" href="/learn/audience/lists">
    Use lists as a base for scoped segments
  </Card>

  <Card title="Campaigns" icon="paper-plane" href="/learn/campaigns/audience-selection">
    Target segments with a campaign
  </Card>
</CardGroup>