Tags & Segments¶

Tags and segments are how you organize subscribers and build targeted audiences for your campaigns.

Tags are simple labels you attach to subscribers (e.g., ios, premium, beta-tester)
Segments are saved queries that dynamically match subscribers based on rules

Tags¶

What Tags Are¶

A tag is a label with a name and a slug. Tags belong to your app, and subscribers can have many tags. The slug is auto-generated from the name (e.g., "Beta Tester" becomes beta-tester). Tag slugs are unique within an app.

Creating Tags¶

Tags are created automatically when you assign them. There's no need to define tags ahead of time.

From the SDK:

MailJawn.setEmail("jane@example.com")
// Tags are passed via the identify endpoint

From the API:

POST /api/v1/projects/{project_id}/subscribers/identify/

{
    "email": "jane@example.com",
    "tags": ["ios", "premium", "beta-tester"]
}

From CSV import: Tags are not directly imported via CSV. After import, use the dashboard or API to tag subscribers.

From subscribe forms: The tag parameter applies a single tag:

<input type="hidden" name="tag" value="website">

How Tags Work¶

Tags are additive — identifying a subscriber with new tags adds them; it never removes existing tags
Tags use a many-to-many relationship through a join table, so each subscriber-tag pair is unique
Tags are matched by slug, so "iOS User" and "ios-user" refer to the same tag

Segments¶

What Segments Are¶

A segment is a saved set of rules that dynamically matches subscribers at query time. Unlike tags (which are manually assigned), segments are computed — a subscriber matches a segment if they satisfy its rules right now.

Segments only match active subscribers. Unsubscribed, bounced, and complained subscribers are always excluded.

Match Logic¶

Each segment has a match mode:

Mode	Logic	Description
`all`	AND	Subscriber must match every rule
`any`	OR	Subscriber must match at least one rule

Rule Types¶

Segments support four rule types:

Tag Rules¶

Match subscribers by their tags.

Operator	Description	Value
`has`	Subscriber has this tag	Single tag slug
`not_has`	Subscriber does not have this tag	Single tag slug
`has_any`	Subscriber has at least one of these tags	Comma-separated slugs
`has_all`	Subscriber has all of these tags	Comma-separated slugs
`has_none`	Subscriber has none of these tags	Comma-separated slugs

Example: Subscribers with the premium tag:

{"type": "tag", "operator": "has", "value": "premium"}

Custom Field Rules¶

Match subscribers by their custom field values.

Operator	Description	Value
`eq`	Equals	Any value
`neq`	Not equals	Any value
`gt`	Greater than	Numeric or string
`gte`	Greater than or equal	Numeric or string
`lt`	Less than	Numeric or string
`lte`	Less than or equal	Numeric or string
`exists`	Field exists on subscriber	(none)
`not_exists`	Field does not exist	(none)

Example: Premium subscribers:

{"type": "custom_field", "field": "app_subscription_status", "operator": "eq", "value": "premium"}

Date Rules¶

Match subscribers by date fields.

Available fields: subscribed_at, first_seen, last_seen, created

Operator	Description
`eq`	On this date (matches any time that calendar day)
`gt`	After this date
`gte`	On or after this date
`lt`	Before this date
`lte`	On or before this date

Date values can be:

Absolute: ISO date format YYYY-MM-DD (e.g., "2025-01-15")
Relative: -Nd format for "N days ago" (e.g., "-30d" means 30 days ago)

Example: Subscribers seen in the last 7 days:

{"type": "date", "field": "last_seen", "operator": "gte", "value": "-7d"}

Email Rules¶

Match subscribers by email address patterns.

Operator	Description	Value
`is`	Exact match (case-insensitive)	Full email
`is_not`	Not this email	Full email
`contains`	Email contains string	Substring
`not_contains`	Email does not contain string	Substring
`starts_with`	Email starts with	Prefix
`ends_with`	Email ends with	Suffix
`domain_is`	Email domain matches	Domain (e.g., `example.com`)
`domain_is_not`	Email domain does not match	Domain

Example: All Gmail subscribers:

{"type": "email", "operator": "domain_is", "value": "gmail.com"}

Full Segment Example¶

A segment for "active premium iOS users who signed up in the last 90 days":

{
    "match": "all",
    "rules": [
        {"type": "tag", "operator": "has", "value": "ios"},
        {"type": "custom_field", "field": "app_subscription_status", "operator": "eq", "value": "premium"},
        {"type": "date", "field": "first_seen", "operator": "gte", "value": "-90d"}
    ]
}

Previewing Segments¶

Before saving a segment, you can preview how many subscribers match and see a sample of up to 10 matching subscribers. This lets you verify your rules before using the segment in a campaign.

Via the API:

POST /api/v1/projects/{project_id}/segments/preview/

Using Segments for Campaigns¶

When creating a campaign, you can target a segment to send only to subscribers who match its rules at send time. Since segments are dynamic, the audience is always current — if a subscriber's status or data changes between when you create the campaign and when it sends, the segment reflects the latest state.

See also: Campaigns > Targeting for how segments are used in campaign delivery.