Segments

Build dynamic contact groups defined by conditions, with help from AI

A segment is a dynamic group of contacts defined by conditions. Unlike a list — 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)”.

Segments can also be managed programmatically. The Audience Segments API lets you create, update, and delete segments and their conditions from your own application.

Creating a Segment

1. Open the Segments page

   Go to Audience → Segments and click Create segment.

2. 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.

3. 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.

4. 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.

5. 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.

6. Save

   Save the segment. The contact count is cached and refreshed in the background as your audience changes.

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 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.

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.

List-Scoped Segments

A segment can optionally be scoped to a single list. 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:

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.

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, 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

Contacts

Set up custom properties to filter on

Lists

Use lists as a base for scoped segments

Campaigns

Target segments with a campaign