---
title: "nextmail.segments"
description: "Every method in this namespace: its signature, its parameters, what it returns and an example."
url: "https://nextmail.sh/docs/python/reference/segments"
area: "Python"
category: "Reference"
---

# nextmail.segments

Every method in this namespace: its signature, its parameters, what it returns and an example.

## Methods

Saved conditions on contacts, such as opened in the last 90 days or a custom field, that narrow a broadcast to the people who match: save, change and delete them, and count who they match.

### `segments.list()`

List the saved segments

```python
def list(
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> builtins.list[SegmentResource]
```

Returns every saved segment of the workspace as a plain list, 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`.

**Parameters**

- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`list[SegmentResource]`, each a dict with `id`, `name`, `description`, `definition`, `createdAt` and `updatedAt`.

**Example**

```python
from nextmail import nextmail

segments = nextmail.segments.list()

for segment in segments:
    print(segment['id'], segment['name'], len(segment['definition']['conditions']))
```

**Notes**

- The SDK retries it after a network failure or a retryable status, since it changes nothing.
- Segments belong to the workspace, not to the key or the person who made them.

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

### `segments.get()`

Get one segment

```python
def get(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SegmentResource
```

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

Scopes: `audiences:read`.

**Parameters**

- `id` (`str`, required): Segment id such as `seg_5d2a9c7e1b4f08a36c1e9b42`.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SegmentResource`.

**Example**

```python
from nextmail import nextmail

segment = nextmail.segments.get('seg_5d2a9c7e1b4f08a36c1e9b42')

print(segment['name'], segment['definition']['match'], segment['definition']['conditions'])
```

**Notes**

- A segment from another workspace, or one that was deleted, is a 404 `segment_not_found`.

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

### `segments.create()`

Save a segment

```python
def create(
    body: SegmentCreate,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SegmentResource
```

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

**Parameters**

- `body['name']` (`str`, required): What the segment is called, 1 to 120 characters.
- `body['description']` (`str | None`): A longer note, up to 500 characters.
- `body['definition']` (`SegmentDefinitionInput`, required): `{'match': 'all' | 'any', 'conditions': [...]}` with 1 to 20 conditions.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SegmentResource` with the new `seg_` id.

**Example**

```python
from nextmail import nextmail

segment = nextmail.segments.create(
    {
        'name': 'Opened in the last 90 days',
        'definition': {
            'match': 'all',
            'conditions': [{'field': 'opened', 'operator': 'within_days', 'days': 90}],
        },
    }
)

nextmail.broadcasts.send(
    {
        'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],
        'segmentId': segment['id'],
        'from': 'Acme <news@acme.com>',
        'subject': 'Thanks for reading',
        'text': 'Hi {{firstName|there}}, here is something for our regular readers.',
    }
)
```

**Notes**

- A workspace keeps at most 100 segments. The 101st is refused with 409 `segment_limit_reached`.
- An audience condition that names an audience the workspace does not have is a 404 `audience_not_found`, and an operator its field does not take is a 422 `invalid_parameter`.
- The SDK does not retry a create after a network failure, so a retry after a lost response can save two. List them and delete the spare.

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

### `segments.update()`

Change a segment

```python
def update(
    id: str,
    patch: SegmentPatch,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SegmentResource
```

A partial update: a field you leave out keeps what it holds. Sending `definition` replaces `match` and every condition at once, and `description: None` 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`.

**Parameters**

- `id` (`str`, required): The `seg_` id of the segment.
- `patch['name']` (`str`): A new name, 1 to 120 characters.
- `patch['description']` (`str | None`): A new note. `None` takes it away.
- `patch['definition']` (`SegmentDefinitionInput`): New conditions, replacing the old ones.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SegmentResource` as it stands after the change.

**Example**

```python
from nextmail import nextmail

segment = nextmail.segments.update(
    'seg_5d2a9c7e1b4f08a36c1e9b42',
    {
        'name': 'Opened in the last 30 days',
        'definition': {
            'conditions': [{'field': 'opened', 'operator': 'within_days', 'days': 30}]
        },
    },
)

print(segment['updatedAt'])
```

**Notes**

- The SDK retries it after a network failure, since sending the same change twice leaves the same segment.
- A segment from another workspace is a 404 `segment_not_found`.

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

### `segments.delete()`

Delete a segment

```python
def delete(
    id: str,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> DeletedSegmentResource
```

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

**Parameters**

- `id` (`str`, required): The `seg_` id of the segment.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`DeletedSegmentResource`, `{'object': 'segment', 'id': ..., 'deleted': True}`.

**Example**

```python
from nextmail import nextmail

removed = nextmail.segments.delete('seg_5d2a9c7e1b4f08a36c1e9b42')

print(removed['id'], removed['deleted'])
```

**Notes**

- The SDK does not retry a delete. A 404 on your own second attempt after a lost response means the first one worked.

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

### `segments.preview()`

Count the contacts a segment matches

```python
def preview(
    body: SegmentPreviewInput,
    *,
    api_key: str | None = None,
    timeout: float | None = None,
) -> SegmentPreviewResource
```

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 `audienceIds`, 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`.

**Parameters**

- `body['definition']` (`SegmentDefinitionInput`, required): The conditions to count, as `create` takes them.
- `body['audienceIds']` (`list[str]`): Up to 10 audiences. Only their subscribed members count. Left out, every contact of the workspace counts.
- `api_key` (`str`): Overrides the client's API key for this call only.
- `timeout` (`float`): Seconds this call may take, the response included, before it raises `NextmailNetworkError` with `is_timeout`. It overrides the client's `timeout` for this call, and `0` turns the limit off.

**Returns**

`SegmentPreviewResource` with `contacts`, the number that match, and `sample`, up to 10 of them.

**Example**

```python
from nextmail import nextmail

preview = nextmail.segments.preview(
    {
        'definition': {
            'conditions': [{'field': 'engaged', 'operator': 'not_within_days', 'days': 180}],
        },
        'audienceIds': ['aud_4c1b8e2a7d9f05c36b4e8a71'],
    }
)

count = preview['contacts']

print(f'{count} people have not opened or clicked in six months')
```

**Notes**

- A condition on a custom field reads each contact it checks and stops at 20,000 of them, answering 422 `segment_too_large`. Narrow it with `audienceIds` first.
- The SDK retries it after a network failure or a retryable status, since it changes nothing.

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