---
title: Filters and segments
description: "Finding contacts by publication, status, source, tag, field, sign-up date and when they were last emailed, saving that as a segment, and sending a campaign to it."
---

## Filters

**Contacts** filters by publication, by status, and by rules that must all hold. The filter is part of the page's
link, so a filtered list can be shared or bookmarked.

| Status | Who |
| --- | --- |
| Subscribed | Subscribed to the publication (or to any, with All publications) and not suppressed. The default |
| Unsubscribed | Unsubscribed from it |
| Suppressed | On the workspace's suppression list |
| Any status | Everyone on it, whatever their status |

| Rule | Compares | Ways |
| --- | --- | --- |
| Field | `first_name` or any field, by the name a merge tag uses | is, is not, contains, is set, is empty, is more than, is less than |
| Tag | The subscription's tags | is, is not |
| Source | Where the subscription came from, as imported | is, contains |
| How they joined | Signed up, imported, or moved from another tool | is |
| Joined | The date consent was given, as a UTC day | in the last N days, on or after, before |
| Last emailed | Campaign emails sent to them, from any publication | in the last N days, not in the last N days, never |

Text compares without regard to case. A rule that is not finished yet has a dashed border and is left out until it
is. "is more than" and "is less than" only match values that are numbers. Tag,
source, how they joined and the joined date hold on the same subscription: with a publication picked, on that
publication's. Opens and clicks are not tracked, so there is no rule for them yet. A filter has at most 10 rules.

## Segments

**Save as segment** keeps the rules as a segment of one publication, and shows how many subscribers it holds
before it is saved. It is offered once every rule is finished and nothing is typed in the search, so what is
saved is what is shown. A segment holds that publication's
subscribers who match, worked out each time it is read, so it follows the list as people join, leave and change.
Suppressed addresses are never in it.

A segment's page shows how many it holds, its newest 100 members, and the campaigns that go to it. **Export CSV**
downloads every member with their consent record, tags and fields. A cell that starts like a spreadsheet formula
is written with a leading `'`, so it opens as text.

Renaming a segment or changing its rules is fine at any time; its publication stays. While rules are being
edited, the count shows what it would become. If campaigns that have not sent go to it and the change adds people,
Save asks once more. A save over someone else's newer one is refused. A segment can be deleted once no campaign
that has not started yet goes to it. Campaigns that already went to it keep its name.

If a segment's stored rules ever stop being readable, it counts nobody, and campaigns that go to it do not send
until the rules are fixed. A segment never quietly becomes everyone on the publication.

## Sending to a segment

On a campaign's Send step, the audience above the count picks **Everyone on** the publication or one of its
segments. The count, the first-batch choice, the field checks and the send all use the same rule, so the number on
the confirm is the number that goes. Who is in the segment is decided when the send starts, as with a whole
publication. Changing the audience does not need a new test.

Send now checks that who it goes to is what you saw: if someone pointed the campaign at another segment, changed the
segment's rules, or many more people match than the count you confirmed, nothing is sent and the count is shown
again.

## API

Rules in the API are objects with `kind`, `op`, `value`, and `field` for a field rule:

| kind | op | value |
| --- | --- | --- |
| `field` | `is`, `is_not`, `contains`, `set`, `unset`, `more`, `less` | text, a number for `more` and `less`, none for `set` and `unset` |
| `tag` | `has`, `lacks` | the tag |
| `source` | `is`, `contains` | text |
| `consent` | `is` | `signup`, `import` or `migrated` |
| `joined` | `within`, `after`, `before` | days (1 to 3,650), or a date as `YYYY-MM-DD` |
| `emailed` | `within`, `not_within`, `never` | days, none for `never` |

```
GET  /api/v1/segments                     contacts:read
POST /api/v1/segments                     contacts:write
GET  /api/v1/segments/{id}/contacts       contacts:read
```

```json
POST /api/v1/segments
{ "name": "Pierce donors", "publicationId": "pub_...",
  "rules": [{ "kind": "tag", "op": "has", "value": "donor" }, { "kind": "field", "field": "county", "op": "is", "value": "Pierce" }] }
```

`GET /api/v1/segments/{id}/contacts?limit=1000&after=<id>` returns members in id order with `next`, the `after` for
the following page, or null on the last one. A segment whose rules no longer work answers 409. Pointing a campaign
at a segment through the API is not available yet; it comes with campaigns in the API.