---
title: "nextmail segments"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://openemail.uk/docs/cli/reference/segments"
area: "CLI"
category: "Reference"
---

# nextmail segments

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `openemail segments list`

List the saved segments

```bash
nextmail segments list [flags]
```

Resolves every saved segment of the workspace as a plain array, newest first, each with its name, its description and its conditions. A workspace keeps at most 100, so the list is never paged.

A segment holds no contacts of its own. Who matches is worked out each time it is read, so use `preview` to count the matches and pass a segment id as `segmentId` to `broadcasts.send` to narrow a broadcast with it.

- Scopes: `audiences:read`.
- Needs a sign-in.
- Aliases: `ls`.

**Examples**

```bash
nextmail segments list
```

Print the raw JSON

```bash
nextmail segments list --json
```

Also available in: API [`GET /segments`](https://openemail.uk/docs/api/reference/audiences#get-segments); TypeScript [`nextmail.segments.list()`](https://openemail.uk/docs/sdk/reference/segments#list); Python [`segments.list()`](https://openemail.uk/docs/python/reference/segments#list); Ruby [`segments.list`](https://openemail.uk/docs/ruby/reference/segments#list); PHP [`segments->list`](https://openemail.uk/docs/php/reference/segments#list); Go [`Segments.List`](https://openemail.uk/docs/go/reference/segments#list); Java [`segments().list`](https://openemail.uk/docs/java/reference/segments#list); C# [`Segments.ListAsync`](https://openemail.uk/docs/csharp/reference/segments#list).

### `openemail segments get`

Get one segment

```bash
nextmail segments get <id> [flags]
```

Fetches one saved segment by its id, with `match` and every condition in `definition`. The conditions come back as they were saved, so the object can be edited and passed to `update` or `preview` as it is.

- Scopes: `audiences:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Arguments**

- `<id>` (required): Segment id such as `seg_5d2a9c7e1b4f08a36c1e9b42`.

**Examples**

```bash
nextmail segments get seg_5d2a9c7e1b4f08a36c1e9b42
```

Print the raw JSON

```bash
nextmail segments get seg_5d2a9c7e1b4f08a36c1e9b42 --json
```

Also available in: API [`GET /segments/{id}`](https://openemail.uk/docs/api/reference/audiences#get-segments-id); TypeScript [`nextmail.segments.get()`](https://openemail.uk/docs/sdk/reference/segments#get); Python [`segments.get()`](https://openemail.uk/docs/python/reference/segments#get); Ruby [`segments.get`](https://openemail.uk/docs/ruby/reference/segments#get); PHP [`segments->get`](https://openemail.uk/docs/php/reference/segments#get); Go [`Segments.Get`](https://openemail.uk/docs/go/reference/segments#get); Java [`segments().get`](https://openemail.uk/docs/java/reference/segments#get); C# [`Segments.GetAsync`](https://openemail.uk/docs/csharp/reference/segments#get).

### `openemail segments create`

Save a segment

```bash
nextmail segments create --name <value> --definition <json|@file|-> [flags]
nextmail segments create --data <json|@file|-> [flags]
```

Saves a set of conditions under a name. `definition.match` is `all` (the default) when a contact has to meet every condition, or `any` when one is enough, and `definition.conditions` holds 1 to 20 of them.

Each condition names a `field` and an `operator`. `email` takes `is`, `is_not`, `contains`, `not_contains` and `ends_with`, and `name` takes those but `ends_with`, plus `is_set` and `is_not_set`. `source` takes `is` and `is_not` with how the contact was added. `created`, `opened`, `clicked` and `engaged` take `within_days` and `not_within_days` with `days`: when the contact was added, the last time they opened or clicked a tracked email from the workspace, and the later of those two. `audience` takes `in` and `not_in` with `audienceId`, and counts only subscribed members. `event` takes `within_days` and `not_within_days` with `event`, a name sent with `events.send`, and `days`. `attribute` takes `key`, the name of a custom field on the contact, with the operators `name` takes. Text is compared without regard to case.

Nothing is sent and no contact changes. A segment is used by passing its id as `segmentId` to `broadcasts.send`.

- Scopes: `audiences:write`.
- Needs a sign-in.
- Aliases: `new`, `add`.

**Flags**

- `--name <value>`: What the segment is called, 1 to 120 characters. Required, here or in `--data`.
- `--description <value>`: A longer note, up to 500 characters.
- `--definition <json|@file|->`: `{ match?: 'all' | 'any', conditions: Array<SegmentCondition> }` with 1 to 20 conditions. JSON shaped as `SegmentDefinitionInput`, inline or from a file with @path. Required, here or in `--data`.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

```bash
nextmail segments create --name 'Opened in the last 90 days' --definition @definition.json
```

Read the whole body from a JSON file

```bash
nextmail segments create --data @segments.json
```

Also available in: API [`POST /segments`](https://openemail.uk/docs/api/reference/audiences#post-segments); TypeScript [`nextmail.segments.create()`](https://openemail.uk/docs/sdk/reference/segments#create); Python [`segments.create()`](https://openemail.uk/docs/python/reference/segments#create); Ruby [`segments.create`](https://openemail.uk/docs/ruby/reference/segments#create); PHP [`segments->create`](https://openemail.uk/docs/php/reference/segments#create); Go [`Segments.Create`](https://openemail.uk/docs/go/reference/segments#create); Java [`segments().create`](https://openemail.uk/docs/java/reference/segments#create); C# [`Segments.CreateAsync`](https://openemail.uk/docs/csharp/reference/segments#create).

### `openemail segments update`

Change a segment

```bash
nextmail segments update <id> [flags]
```

A partial update: a field you leave out keeps what it holds. Sending `definition` replaces `match` and every condition at once, and `description: null` takes the description away.

A broadcast already sent or scheduled keeps the conditions it was given, so a change here only reaches the broadcasts sent after it.

- Scopes: `audiences:write`.
- Needs a sign-in.
- Aliases: `edit`.

**Arguments**

- `<id>` (required): The `seg_` id of the segment.

**Flags**

- `--name <value>`: A new name, 1 to 120 characters.
- `--description <value>`: A new note. Null takes it away.
- `--definition <json|@file|->`: New conditions, replacing the old ones. JSON shaped as `SegmentDefinitionInput`, inline or from a file with @path.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

With optional flags

```bash
nextmail segments update seg_5d2a9c7e1b4f08a36c1e9b42 --name 'Opened in the last 30 days'
```

Print the raw JSON

```bash
nextmail segments update seg_5d2a9c7e1b4f08a36c1e9b42 --name 'Opened in the last 30 days' --json
```

Also available in: API [`PATCH /segments/{id}`](https://openemail.uk/docs/api/reference/audiences#patch-segments-id); TypeScript [`nextmail.segments.update()`](https://openemail.uk/docs/sdk/reference/segments#update); Python [`segments.update()`](https://openemail.uk/docs/python/reference/segments#update); Ruby [`segments.update`](https://openemail.uk/docs/ruby/reference/segments#update); PHP [`segments->update`](https://openemail.uk/docs/php/reference/segments#update); Go [`Segments.Update`](https://openemail.uk/docs/go/reference/segments#update); Java [`segments().update`](https://openemail.uk/docs/java/reference/segments#update); C# [`Segments.UpdateAsync`](https://openemail.uk/docs/csharp/reference/segments#update).

### `openemail segments delete`

Delete a segment

```bash
nextmail segments delete <id> [flags]
```

Deletes the saved segment. No contact is touched, and a broadcast already sent or scheduled keeps the conditions it was given.

A draft that still names the segment in `segmentId` is refused with 404 `segment_not_found` when it is sent, until it names another segment or none.

- Scopes: `audiences:write`.
- Needs a sign-in.
- Asks you to confirm.
- Aliases: `rm`, `del`, `remove`.

**Arguments**

- `<id>` (required): The `seg_` id of the segment.

**Examples**

```bash
nextmail segments delete seg_5d2a9c7e1b4f08a36c1e9b42
```

Skip the confirmation, for scripts

```bash
nextmail segments delete seg_5d2a9c7e1b4f08a36c1e9b42 --yes
```

Also available in: API [`DELETE /segments/{id}`](https://openemail.uk/docs/api/reference/audiences#delete-segments-id); TypeScript [`nextmail.segments.delete()`](https://openemail.uk/docs/sdk/reference/segments#delete); Python [`segments.delete()`](https://openemail.uk/docs/python/reference/segments#delete); Ruby [`segments.delete`](https://openemail.uk/docs/ruby/reference/segments#delete); PHP [`segments->delete`](https://openemail.uk/docs/php/reference/segments#delete); Go [`Segments.Delete`](https://openemail.uk/docs/go/reference/segments#delete); Java [`segments().delete`](https://openemail.uk/docs/java/reference/segments#delete); C# [`Segments.DeleteAsync`](https://openemail.uk/docs/csharp/reference/segments#delete).

### `openemail segments preview`

Count the contacts a segment matches

```bash
nextmail segments preview --definition <json|@file|-> [flags]
nextmail segments preview --data <json|@file|-> [flags]
```

Counts the contacts a set of conditions matches now and returns up to 10 of them, without saving or sending anything. Pass the `definition` of a saved segment to count it, or new conditions to try them first.

With `--audience-ids`, only the subscribed members of those audiences count, which is the number a broadcast to them with this segment would start from before unsubscribes and suppressions are taken out. `broadcasts.preview` with `segmentId` gives that final number.

- Scopes: `audiences:read`.
- Needs a sign-in.

**Flags**

- `--definition <json|@file|->`: The conditions to count, as `create` takes them. JSON shaped as `SegmentDefinitionInput`, inline or from a file with @path. Required, here or in `--data`.
- `--audience-ids <a,b>` (repeatable): Up to 10 audiences. Only their subscribed members count. Left out, every contact of the workspace counts.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

The required values only

```bash
nextmail segments preview --definition @definition.json
```

With optional flags

```bash
nextmail segments preview --definition @definition.json --audience-ids aud_4c1b8e2a7d9f05c36b4e8a71
```

Read the whole body from a JSON file

```bash
nextmail segments preview --data @segments.json
```

Also available in: API [`POST /segments/preview`](https://openemail.uk/docs/api/reference/audiences#post-segments-preview); TypeScript [`nextmail.segments.preview()`](https://openemail.uk/docs/sdk/reference/segments#preview); Python [`segments.preview()`](https://openemail.uk/docs/python/reference/segments#preview); Ruby [`segments.preview`](https://openemail.uk/docs/ruby/reference/segments#preview); PHP [`segments->preview`](https://openemail.uk/docs/php/reference/segments#preview); Go [`Segments.Preview`](https://openemail.uk/docs/go/reference/segments#preview); Java [`segments().preview`](https://openemail.uk/docs/java/reference/segments#preview); C# [`Segments.PreviewAsync`](https://openemail.uk/docs/csharp/reference/segments#preview).