--- title: "client.Segments" description: "Every method in this namespace: its signature, its parameters, what it returns and an example." url: "https://openemail.uk/docs/csharp/reference/segments" area: "C#" category: "Reference" --- # client.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.ListAsync` List the saved segments ```csharp Task> ListAsync( string? apiKey = null, CancellationToken cancellationToken = default) ``` 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 `Segments.PreviewAsync` to count the matches and pass a segment id as `segmentId` to `Broadcasts.SendAsync` to narrow a broadcast with it. Scopes: `audiences:read`. **Parameters** - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** An `IReadOnlyList`, each with `id`, `name`, `description`, `definition`, `createdAt` and `updatedAt`. **Example** ```csharp var segments = await client.Segments.ListAsync(); foreach (var segment in segments) { Console.WriteLine($"{segment["id"]} {segment["name"]}"); } ``` **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://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); CLI [`openemail segments list`](https://openemail.uk/docs/cli/reference/segments#segments-list). ### `Segments.GetAsync` Get one segment ```csharp Task GetAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` Returns one saved segment by its id, with `match` and every condition in `definition`. The conditions come back as they were saved, so they can be edited and passed to `Segments.UpdateAsync` or `Segments.PreviewAsync` as they are. Scopes: `audiences:read`. **Parameters** - `id` (`string`, required): Segment id such as `seg_5d2a9c7e1b4f08a36c1e9b42`. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the segment. **Example** ```csharp var segment = await client.Segments.GetAsync("seg_5d2a9c7e1b4f08a36c1e9b42"); Console.WriteLine($"{segment["name"]} matches {segment["definition"]?["match"]}"); ``` **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://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); CLI [`openemail segments get`](https://openemail.uk/docs/cli/reference/segments#segments-get). ### `Segments.CreateAsync` Save a segment ```csharp Task CreateAsync( IReadOnlyDictionary body, string? apiKey = null, CancellationToken cancellationToken = default) ``` Saves a set of conditions under a name. `match` in `definition` is `all` (the default) when a contact has to meet every condition, or `any` when one is enough, and its `conditions` hold 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.SendAsync`, 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.SendAsync`. Scopes: `audiences:write`. **Parameters** - `name` (`string`, required): What the segment is called, 1 to 120 characters. - `description` (`string`): A longer note, up to 500 characters. - `definition` (`dictionary`, required): `match` (`all` or `any`) and `conditions`, 1 to 20 of them. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the segment, with its new `seg_` id. **Example** ```csharp var segment = await client.Segments.CreateAsync(new Body { ["name"] = "Opened in the last 90 days", ["definition"] = new Body { ["match"] = "all", ["conditions"] = new[] { new Body { ["field"] = "opened", ["operator"] = "within_days", ["days"] = 90 } }, }, }); await client.Broadcasts.SendAsync(new Body { ["audienceIds"] = new[] { "aud_4c1b8e2a7d9f05c36b4e8a71" }, ["segmentId"] = (string?)segment["id"], ["from"] = "Acme ", ["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://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); CLI [`openemail segments create`](https://openemail.uk/docs/cli/reference/segments#segments-create). ### `Segments.UpdateAsync` Change a segment ```csharp Task UpdateAsync( string id, IReadOnlyDictionary patch, string? apiKey = null, CancellationToken cancellationToken = default) ``` A partial update: a field you leave out keeps what it holds. Sending `definition` replaces `match` and every condition at once, and `description` set to 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`. **Parameters** - `id` (`string`, required): The `seg_` id of the segment. - `name` (`string`): A new name, 1 to 120 characters. - `description` (`string or null`): A new note. Null takes it away. - `definition` (`dictionary`): New conditions, replacing the old ones. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` for the segment as it stands after the change. **Example** ```csharp var segment = await client.Segments.UpdateAsync("seg_5d2a9c7e1b4f08a36c1e9b42", new Body { ["name"] = "Opened in the last 30 days", ["definition"] = new Body { ["conditions"] = new[] { new Body { ["field"] = "opened", ["operator"] = "within_days", ["days"] = 30 } }, }, }); Console.WriteLine(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://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); CLI [`openemail segments update`](https://openemail.uk/docs/cli/reference/segments#segments-update). ### `Segments.DeleteAsync` Delete a segment ```csharp Task DeleteAsync( string id, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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` (`string`, required): The `seg_` id of the segment. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `object` set to `segment`, `id` and `deleted` set to true. **Example** ```csharp var removed = await client.Segments.DeleteAsync("seg_5d2a9c7e1b4f08a36c1e9b42"); Console.WriteLine($"{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://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); CLI [`openemail segments delete`](https://openemail.uk/docs/cli/reference/segments#segments-delete). ### `Segments.PreviewAsync` Count the contacts a segment matches ```csharp Task PreviewAsync( IReadOnlyDictionary body, string? apiKey = null, CancellationToken cancellationToken = default) ``` 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.PreviewAsync` with `segmentId` gives that final number. Scopes: `audiences:read`. **Parameters** - `definition` (`dictionary`, required): The conditions to count, as `Segments.CreateAsync` takes them. - `audienceIds` (`IEnumerable`): Up to 10 audiences. Only their subscribed members count. Left out, every contact of the workspace counts. - `apiKey` (`string?`): Overrides the client's API key for this call only. - `cancellationToken` (`CancellationToken`): Cancels the request. **Returns** A `JsonObject` with `contacts`, the number that match, and `sample`, up to 10 of them. **Example** ```csharp var preview = await client.Segments.PreviewAsync(new Body { ["definition"] = new Body { ["conditions"] = new[] { new Body { ["field"] = "engaged", ["operator"] = "not_within_days", ["days"] = 180 } }, }, ["audienceIds"] = new[] { "aud_4c1b8e2a7d9f05c36b4e8a71" }, }); Console.WriteLine($"{preview["contacts"]} 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://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); CLI [`openemail segments preview`](https://openemail.uk/docs/cli/reference/segments#segments-preview).