# Segments

Manage tags and segment rules for targeted notifications.

Source: https://statusdashboard.com/docs/notifications/segments

> This is a plan-gated feature. If it isn't available in your account, visit the [Billing](/docs/org-mgmt/billing) page or contact support to review your options.

Segments let you target event notifications to specific audiences instead of every subscriber on a status dashboard. You assign **tags** to contacts in a registry, then define **segments** as named OR-rules over those tags and apply include or exclude targeting on individual events.

Manage tags and segments from [Segments](/app/settings/segments). Tag assignments are independent of dashboard subscriptions. The sections below define the concepts, counters, and how to attach segment rules when publishing an event.

***

## Concepts
Tag assignments are stored independently of dashboard subscriptions. A contact can hold a tag whether or not they subscribe to any status dashboard. Unsubscribing does not remove tags.

| Term             | Meaning                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------- |
| **Tag**          | A label (e.g. Executive) assigned to an email address or phone number                     |
| **Registry**     | The list of who holds which tag, each with a display name and contact                     |
| **Display name** | A human-readable label for a registry entry (e.g. Jane Doe, CEO) — for admin display only |
| **Segment**      | A named OR-rule over tags (e.g. Executives = Executive OR Director)                       |

## Counters
Tag and segment counters show different numbers because they measure different things.

### Tags — **x contacts**
Each tag shows how many **registry assignments** it has: email addresses and phone numbers labeled with that tag.

* Includes **email, SMS, and WhatsApp** contacts
* Counts everyone in the tag registry, whether or not they subscribe to a status dashboard
* Does **not** change when someone unsubscribes — tag assignments are stored separately from subscriptions
* Updates when you add a contact in **Tag contact** or remove one from the **Tag registry**

**Contacts** = who you have labeled with that tag.

### Segments — **Matches** and **x active**
Each segment shows two pieces of information:

* **Matches** — the segment's tags combined with OR logic (e.g. `[Executive] OR [Director]`)
* **Active** — how many people in the segment are **currently active email subscribers**

**Active** is a narrower, read-time metric. A contact counts toward **active** only when **all** of the following are true:

1. They are in the segment through an **email** tag assignment (OR across the segment's tags)
2. They are a **verified** email subscriber on at least one dashboard
3. They have **at least one component** selected on that subscription

SMS- and WhatsApp-tagged contacts are **not** included in the active count. Someone can be tagged and appear in **Matches** but show **0 active** if they never subscribed, unsubscribed, or are not verified.

|                            | Tags                   | Segments                                         |
| -------------------------- | ---------------------- | ------------------------------------------------ |
| **Badge**                  | x contacts             | x active                                         |
| **What it counts**         | Registry assignments   | Registry emails that are also active subscribers |
| **Channels**               | Email + SMS + WhatsApp | Email only                                       |
| **Requires subscription?** | No                     | Yes (verified, with components)                  |
| **When computed**          | Stored on the tag      | Computed at read time                            |

A segment might match many tagged contacts but only a subset may be **active** subscribers today. That distinction matters when you apply segment targeting on events.

## Managing segments and tags
The Segments page has four cards:

| Card             | Purpose                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------- |
| **Tags**         | Create, rename, and delete tag definitions                                                    |
| **Segments**     | Create, edit, and delete segment rules                                                        |
| **Tag contact**  | Assign email, SMS, or WhatsApp contacts to a tag                                              |
| **Tag registry** | Browse tagged contacts; filter by tag badge; **Channel** column distinguishes SMS vs WhatsApp |

### Creating a tag
1. Click **New Tag** on the **Tags** card.
2. Enter a **Tag name** (required).
3. Click **Create** — the tag appears in the Tags list, segment dialogs, and registry filters.

You can rename a tag later with the edit control on the Tags card. Delete is available on the same row when the tag is unused.

### Assigning a tag to a contact
1. In **Tag contact**, enter a **Display name** — who this contact is (e.g. `Jane Doe, CEO`). This label is for your team only; segments and notifications still match on the email or phone number.
2. Choose **Email**, **SMS**, or **WhatsApp**.
3. Enter the contact — email address, or country + phone number for SMS or WhatsApp (converted to E.164).
4. Select the tag from the dropdown.
5. Click **Add** — the entry appears in the **Tag registry** table with the display name, contact, channel, and tag.

Phone numbers are validated to international standards and stored in E.164 format (e.g. `+14155552671`). The same number may appear twice on a tag when tagged separately for SMS and WhatsApp.

The **Tag registry** table shows **Name** first so long lists stay scannable; the email or phone appears in the **Contact** column.

Filter the table with the **Filter by tag** badges (**All** or a specific tag). Remove an assignment with the delete control on a row — a confirmation dialog appears before removal.

### Creating a segment
1. Click **New Segment** on the **Segments** card.
2. Enter a **Segment name**.
3. Optionally select one or more tags (OR logic: a contact in any selected tag is part of the segment). Tags can be added later if none exist yet.
4. Click **Create** — the segment appears in the list with its match rule and active count.

You can edit a segment later to change its name or add/remove tags using the edit control on the Segments card.

### Deleting a tag
1. On the **Tags** card, click the delete control on a tag row.
2. Confirm in the dialog — deletion is permanent.
3. A tag can only be deleted when it has **no registry contacts** and is **not referenced by any segment**. Otherwise the admin console returns a clear error.

### Deleting a segment
1. On the **Segments** card, click the delete control on a segment row.
2. Confirm in the dialog — deletion is permanent.
3. Tags and registry assignments are **not** removed when a segment is deleted.

**Constraints:**

* Maximum **25** segments per organization — new segments cannot be created once the limit is reached.
* Maximum **50** tags per organization — new tags cannot be created once the limit is reached.
* Maximum **5** tags per segment — a segment may have **zero** tags (matches no contacts until tags are added).
* Maximum **1,000** contacts per tag in the registry — additional assignments to that tag are rejected once the limit is reached.
* Tag and segment names must be **unique** within your organization (case-insensitive), **1–50 characters**.
* A contact cannot be assigned to the same tag twice — duplicate contact and tag combinations are rejected.
* Display names are **required**, **1–100 characters**, and stored as entered (trimmed).
* Email addresses must be valid; SMS and WhatsApp numbers must be valid E.164 (e.g. `+14155552671`).
* The same E.164 may be assigned to the same tag once per channel (SMS and WhatsApp are independent).
* Tag assignments are **not** removed when a contact unsubscribes from a status dashboard.

## Plan changes
If your organization **downgrades** to a plan without segments:

* The Segments page is hidden and segment APIs return `403`.
* **Event segment targeting** is hidden on create/edit; stored `segmentNotification` on existing events is not removed.
* **Notifications** ignore stored segment targeting until the feature is enabled again — all matching subscribers are notified as usual.
* **Tags, segments, and registry data** remain in your organization and are available again after you re-upgrade.

## Event notification targeting
When the segments feature is enabled for your organization, you can configure **per-event** segment targeting on the **Segments** tab of the create/edit event page (after **Notifications**). See [Event segment targeting](/docs/events/segments) for details.