# Create a segment (/docs/api-reference/segments/create-segment)

A segment is a filter over the environment's contacts, evaluated whenever it is used, so its contacts are always current.

`POST https://api.coss.com/v1/segments`

Authenticate with your API key as a bearer token (`Authorization: Bearer coss_test_…`). Responses are JSON with snake_case fields; errors are `{ error: { type, code, message, param?, issues?, request_id } }` (https://coss.com/docs/api-reference/errors.md).

## Request body

- `name` (string, required, 1-200 characters): Your name for the segment, unique in the environment.
- `filter` (object, required): Which contacts belong to the segment. Conditions on `property` (custom properties), `email`, `audience` membership, `topic` subscription and `created_at`; one level of nested `{ match, conditions }` groups.
  - `version` (1, required): The filter's format. Always 1.
  - `match` ("all" | "any", required): `all`: every condition must hold; `any`: one is enough.
  - `conditions` (object[], required, at least 1 item): Conditions, or `{ match, conditions }` groups of them. At most 20 in all.
    - One of (1):
      - `field` ("property", required)
      - `key` (string, required): The custom property to test.
      - `op` ("eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "exists" | "not_exists", required): How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value.
      - `value` (string | number | boolean | (string | number | boolean)[], at most 2000 characters, 1-100 items): A list for `in`/`not_in`; none for `exists`/`not_exists`.
    - One of (2):
      - `field` ("email", required)
      - `op` ("eq" | "ends_with" | "contains", required): How to compare the contact's address.
      - `value` (string, required, 1-254 characters): What to compare it with.
    - One of (3):
      - `field` ("audience", required)
      - `op` ("in" | "not_in", required): Whether the contact is in the audience.
      - `audience_id` (string, required): The audience's id.
    - One of (4):
      - `field` ("topic", required)
      - `op` ("subscribed" | "not_subscribed", required): Whether emails about the topic reach the contact.
      - `topic` (string, required): The topic's key.
    - One of (5):
      - `field` ("created_at", required)
      - `op` ("before" | "after" | "within_days", required): `before` or `after` a time, or created `within_days` the last days.
      - `value` (string | integer, required, date-time, 1-3650): A timestamp for `before`/`after`, a number of days for `within_days`.
    - One of (6):
      - `match` ("all" | "any", required): `all`: every condition must hold; `any`: one is enough.
      - `conditions` (object[], required, at least 1 item): The group's conditions.
        - One of (1):
          - `field` ("property", required)
          - `key` (string, required): The custom property to test.
          - `op` ("eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "exists" | "not_exists", required): How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value.
          - `value` (string | number | boolean | (string | number | boolean)[], at most 2000 characters, 1-100 items): A list for `in`/`not_in`; none for `exists`/`not_exists`.
        - One of (2):
          - `field` ("email", required)
          - `op` ("eq" | "ends_with" | "contains", required): How to compare the contact's address.
          - `value` (string, required, 1-254 characters): What to compare it with.
        - One of (3):
          - `field` ("audience", required)
          - `op` ("in" | "not_in", required): Whether the contact is in the audience.
          - `audience_id` (string, required): The audience's id.
        - One of (4):
          - `field` ("topic", required)
          - `op` ("subscribed" | "not_subscribed", required): Whether emails about the topic reach the contact.
          - `topic` (string, required): The topic's key.
        - One of (5):
          - `field` ("created_at", required)
          - `op` ("before" | "after" | "within_days", required): `before` or `after` a time, or created `within_days` the last days.
          - `value` (string | integer, required, date-time, 1-3650): A timestamp for `before`/`after`, a number of days for `within_days`.

## Example request

TypeScript (the `coss` package):

```ts
import { Coss } from "coss";

const coss = new Coss({
  apiKey: process.env.COSS_API_KEY,
  baseUrl: "https://api.coss.com",
});

const { data, error } = await coss.email.segments.create({
  name: "Pro customers",
  filter: {
    version: 1,
    match: "all",
    conditions: [
      {
        field: "property",
        key: "plan",
        op: "eq",
        value: "pro",
      },
      {
        match: "any",
        conditions: [
          {
            field: "email",
            op: "ends_with",
            value: "@acme.com",
          },
          {
            field: "audience",
            op: "in",
            audience_id: "aud_01k7c8m4q2f3e9v6t5r1n0p8yz",
          },
        ],
      },
    ],
  },
});
```

HTTP:

```sh
curl -X POST "https://api.coss.com/v1/segments" \
  -H "Authorization: Bearer $COSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Pro customers",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "property",
        "key": "plan",
        "op": "eq",
        "value": "pro"
      },
      {
        "match": "any",
        "conditions": [
          {
            "field": "email",
            "op": "ends_with",
            "value": "@acme.com"
          },
          {
            "field": "audience",
            "op": "in",
            "audience_id": "aud_01k7c8m4q2f3e9v6t5r1n0p8yz"
          }
        ]
      }
    ]
  }
}'
```

Python:

```python
from coss import Coss
from coss import Coss, SegmentFilter, SegmentFilterConditionsItemKey, SegmentFilterConditionsItemConditions, SegmentFilterConditionsItemConditionsConditionsItem_Email, SegmentFilterConditionsItemConditionsConditionsItem_Audience

client = Coss()  # api_key= or COSS_API_KEY

client.email.segments.create(
    name="Pro customers",
    filter=SegmentFilter(
        version=1,
        match="all",
        conditions=[
            SegmentFilterConditionsItemKey(
                field="property",
                key="plan",
                op="eq",
                value="pro",
            ),
            SegmentFilterConditionsItemConditions(
                match="any",
                conditions=[
                    SegmentFilterConditionsItemConditionsConditionsItem_Email(
                        op="ends_with",
                        value="@acme.com",
                    ),
                    SegmentFilterConditionsItemConditionsConditionsItem_Audience(
                        op="in",
                        audience_id="aud_01k7c8m4q2f3e9v6t5r1n0p8yz",
                    )
                ],
            )
        ],
    ),
)
```

Go:

```go
import (
	"context"

	coss "github.com/cosscom/coss-go"
	cossclient "github.com/cosscom/coss-go/client"
	email "github.com/cosscom/coss-go/email"
)

client := cossclient.NewClient() // option.WithAPIKey(…) or COSS_API_KEY

request := &email.CreateSegmentRequest{
    Name: "Pro customers",
    Filter: &coss.SegmentFilter{
        Version: 1,
        Match: coss.SegmentFilterMatchAll,
        Conditions: []*coss.SegmentFilterConditionsItem{
            &coss.SegmentFilterConditionsItem{
                SegmentFilterConditionsItemKey: &coss.SegmentFilterConditionsItemKey{
                    Field: coss.SegmentFilterConditionsItemKeyFieldProperty,
                    Key: "plan",
                    Op: coss.SegmentFilterConditionsItemKeyOpEq,
                    Value: &coss.SegmentFilterConditionsItemKeyValue{
                        String: "pro",
                    },
                },
            },
            &coss.SegmentFilterConditionsItem{
                SegmentFilterConditionsItemConditions: &coss.SegmentFilterConditionsItemConditions{
                    Match: coss.SegmentFilterConditionsItemConditionsMatchAny,
                    Conditions: []*coss.SegmentFilterConditionsItemConditionsConditionsItem{
                        &coss.SegmentFilterConditionsItemConditionsConditionsItem{
                            Email: &coss.SegmentFilterConditionsItemConditionsConditionsItemEmail{
                                Op: coss.SegmentFilterConditionsItemConditionsConditionsItemEmailOpEndsWith,
                                Value: "@acme.com",
                            },
                        },
                        &coss.SegmentFilterConditionsItemConditionsConditionsItem{
                            Audience: &coss.SegmentFilterConditionsItemConditionsConditionsItemAudience{
                                Op: coss.SegmentFilterConditionsItemConditionsConditionsItemAudienceOpIn,
                                AudienceID: "aud_01k7c8m4q2f3e9v6t5r1n0p8yz",
                            },
                        },
                    },
                },
            },
        },
    },
}
client.Email.Segments.Create(
    context.TODO(),
    request,
)
```

Ruby:

```ruby
require "coss"

client = Coss::Client.new # api_key: or COSS_API_KEY

client.email.segments.create(
  name: "Pro customers",
  filter: {
    version: 1,
    match: "all",
    conditions: [{
      field: "property",
      key: "plan",
      op: "eq",
      value: "pro"
    }, {
      match: "any",
      conditions: [{
        field: "email",
        op: "ends_with",
        value: "@acme.com"
      }, {
        field: "audience",
        op: "in",
        audience_id: "aud_01k7c8m4q2f3e9v6t5r1n0p8yz"
      }],
      field: "property",
      key: "string",
      op: "eq"
    }]
  }
)
```

PHP:

```php
<?php

use Coss\Coss;
use Coss\Email\Segments\Requests\CreateSegmentRequest;
use Coss\Types\SegmentFilter;
use Coss\Types\SegmentFilterConditionsItemKey;
use Coss\Types\SegmentFilterConditionsItemKeyField;
use Coss\Types\SegmentFilterConditionsItemKeyOp;
use Coss\Types\SegmentFilterMatch;

$client = new Coss(); // apiKey: or COSS_API_KEY

$client->email->segments->create(
    new CreateSegmentRequest([
        'name' => 'Pro customers',
        'filter' => new SegmentFilter([
            'version' => 1,
            'match' => SegmentFilterMatch::All->value,
            'conditions' => [
                new SegmentFilterConditionsItemKey([
                    'field' => SegmentFilterConditionsItemKeyField::Property->value,
                    'key' => 'plan',
                    'op' => SegmentFilterConditionsItemKeyOp::Eq->value,
                    'value' => 'pro',
                ]),
                new SegmentFilterConditionsItemKey([
                    'field' => SegmentFilterConditionsItemKeyField::Property->value,
                    'key' => 'value',
                    'op' => SegmentFilterConditionsItemKeyOp::Eq->value,
                ]),
            ],
        ]),
    ]),
);
```

Java:

```java
import com.coss.Coss;
import com.coss.resources.email.segments.requests.CreateSegmentRequest;
import com.coss.types.SegmentFilter;
import com.coss.types.SegmentFilterConditionsItem;
import com.coss.types.SegmentFilterConditionsItemConditions;
import com.coss.types.SegmentFilterConditionsItemConditionsConditionsItem;
import com.coss.types.SegmentFilterConditionsItemConditionsConditionsItemAudience;
import com.coss.types.SegmentFilterConditionsItemConditionsConditionsItemAudienceOp;
import com.coss.types.SegmentFilterConditionsItemConditionsConditionsItemEmail;
import com.coss.types.SegmentFilterConditionsItemConditionsConditionsItemEmailOp;
import com.coss.types.SegmentFilterConditionsItemConditionsMatch;
import com.coss.types.SegmentFilterConditionsItemKey;
import com.coss.types.SegmentFilterConditionsItemKeyField;
import com.coss.types.SegmentFilterConditionsItemKeyOp;
import com.coss.types.SegmentFilterConditionsItemKeyValue;
import com.coss.types.SegmentFilterMatch;
import java.util.Arrays;
import java.util.Optional;

Coss client = Coss.builder().build(); // .apiKey(…) or COSS_API_KEY

client.email().segments().create(
    CreateSegmentRequest
        .builder()
        .name("Pro customers")
        .filter(
            SegmentFilter
                .builder()
                .version(1.0)
                .match(SegmentFilterMatch.ALL)
                .conditions(
                    Arrays.asList(
                        SegmentFilterConditionsItem.of(
                            SegmentFilterConditionsItemKey
                                .builder()
                                .field(SegmentFilterConditionsItemKeyField.PROPERTY)
                                .key("plan")
                                .op(SegmentFilterConditionsItemKeyOp.EQ)
                                .value(
                                    Optional.of(
                                        SegmentFilterConditionsItemKeyValue.of("pro")
                                    )
                                )
                                .build()
                        ),
                        SegmentFilterConditionsItem.of(
                            SegmentFilterConditionsItemConditions
                                .builder()
                                .match(SegmentFilterConditionsItemConditionsMatch.ANY)
                                .conditions(
                                    Arrays.asList(
                                        SegmentFilterConditionsItemConditionsConditionsItem.email(
                                            SegmentFilterConditionsItemConditionsConditionsItemEmail
                                                .builder()
                                                .op(SegmentFilterConditionsItemConditionsConditionsItemEmailOp.ENDS_WITH)
                                                .value("@acme.com")
                                                .build()
                                        ),
                                        SegmentFilterConditionsItemConditionsConditionsItem.audience(
                                            SegmentFilterConditionsItemConditionsConditionsItemAudience
                                                .builder()
                                                .op(SegmentFilterConditionsItemConditionsConditionsItemAudienceOp.IN)
                                                .audienceId("aud_01k7c8m4q2f3e9v6t5r1n0p8yz")
                                                .build()
                                        )
                                    )
                                )
                                .build()
                        )
                    )
                )
                .build()
        )
        .build()
);
```

.NET:

```csharp
using Coss;
using Coss.Email;

var client = new CossClient(); // apiKey: or COSS_API_KEY

await client.Email.Segments.CreateAsync(
    new CreateSegmentRequest
    {
        Name = "Pro customers",
        Filter = new SegmentFilter
        {
            Version = 1,
            Match = SegmentFilterMatch.All,
            Conditions = new List<
                OneOf<
                    SegmentFilterConditionsItemKey,
                    SegmentFilterConditionsItemOne,
                    SegmentFilterConditionsItemAudienceId,
                    SegmentFilterConditionsItemTopic,
                    SegmentFilterConditionsItemField,
                    SegmentFilterConditionsItemConditions
                >
            >()
            {
                new SegmentFilterConditionsItemKey
                {
                    Field = SegmentFilterConditionsItemKeyField.Property,
                    Key = "plan",
                    Op = SegmentFilterConditionsItemKeyOp.Eq,
                    Value = "pro",
                },
                new SegmentFilterConditionsItemConditions
                {
                    Match = SegmentFilterConditionsItemConditionsMatch.Any,
                    Conditions = new List<SegmentFilterConditionsItemConditionsConditionsItem>()
                    {
                        new SegmentFilterConditionsItemConditionsConditionsItem(
                            new Coss.SegmentFilterConditionsItemConditionsConditionsItem.Email(
                                new SegmentFilterConditionsItemConditionsConditionsItemEmail
                                {
                                    Op =
                                        SegmentFilterConditionsItemConditionsConditionsItemEmailOp.EndsWith,
                                    Value = "@acme.com",
                                }
                            )
                        ),
                        new SegmentFilterConditionsItemConditionsConditionsItem(
                            new SegmentFilterConditionsItemConditionsConditionsItem.Audience(
                                new SegmentFilterConditionsItemConditionsConditionsItemAudience
                                {
                                    Op =
                                        SegmentFilterConditionsItemConditionsConditionsItemAudienceOp.In,
                                    AudienceId = "aud_01k7c8m4q2f3e9v6t5r1n0p8yz",
                                }
                            )
                        ),
                    },
                },
            },
        },
    }
);
```

## Response 201

The new segment.

- `object` ("segment", required)
- `id` (string, required)
- `name` (string, required): Your name for the segment, unique in the environment.
- `filter` (object, required): Which contacts belong to the segment. Conditions on `property` (custom properties), `email`, `audience` membership, `topic` subscription and `created_at`; one level of nested `{ match, conditions }` groups.
  - `version` (1, required): The filter's format. Always 1.
  - `match` ("all" | "any", required): `all`: every condition must hold; `any`: one is enough.
  - `conditions` (object[], required, at least 1 item): Conditions, or `{ match, conditions }` groups of them. At most 20 in all.
    - One of (1):
      - `field` ("property", required)
      - `key` (string, required): The custom property to test.
      - `op` ("eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "exists" | "not_exists", required): How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value.
      - `value` (string | number | boolean | (string | number | boolean)[], at most 2000 characters, 1-100 items): A list for `in`/`not_in`; none for `exists`/`not_exists`.
    - One of (2):
      - `field` ("email", required)
      - `op` ("eq" | "ends_with" | "contains", required): How to compare the contact's address.
      - `value` (string, required, 1-254 characters): What to compare it with.
    - One of (3):
      - `field` ("audience", required)
      - `op` ("in" | "not_in", required): Whether the contact is in the audience.
      - `audience_id` (string, required): The audience's id.
    - One of (4):
      - `field` ("topic", required)
      - `op` ("subscribed" | "not_subscribed", required): Whether emails about the topic reach the contact.
      - `topic` (string, required): The topic's key.
    - One of (5):
      - `field` ("created_at", required)
      - `op` ("before" | "after" | "within_days", required): `before` or `after` a time, or created `within_days` the last days.
      - `value` (string | integer, required, date-time, 1-3650): A timestamp for `before`/`after`, a number of days for `within_days`.
    - One of (6):
      - `match` ("all" | "any", required): `all`: every condition must hold; `any`: one is enough.
      - `conditions` (object[], required, at least 1 item): The group's conditions.
        - One of (1):
          - `field` ("property", required)
          - `key` (string, required): The custom property to test.
          - `op` ("eq" | "neq" | "in" | "not_in" | "gt" | "gte" | "lt" | "lte" | "contains" | "starts_with" | "exists" | "not_exists", required): How to compare: `eq`, `neq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `contains`, `starts_with`, or `exists` and `not_exists`, which take no value.
          - `value` (string | number | boolean | (string | number | boolean)[], at most 2000 characters, 1-100 items): A list for `in`/`not_in`; none for `exists`/`not_exists`.
        - One of (2):
          - `field` ("email", required)
          - `op` ("eq" | "ends_with" | "contains", required): How to compare the contact's address.
          - `value` (string, required, 1-254 characters): What to compare it with.
        - One of (3):
          - `field` ("audience", required)
          - `op` ("in" | "not_in", required): Whether the contact is in the audience.
          - `audience_id` (string, required): The audience's id.
        - One of (4):
          - `field` ("topic", required)
          - `op` ("subscribed" | "not_subscribed", required): Whether emails about the topic reach the contact.
          - `topic` (string, required): The topic's key.
        - One of (5):
          - `field` ("created_at", required)
          - `op` ("before" | "after" | "within_days", required): `before` or `after` a time, or created `within_days` the last days.
          - `value` (string | integer, required, date-time, 1-3650): A timestamp for `before`/`after`, a number of days for `within_days`.
- `created_at` (string, required, date-time)
- `updated_at` (string, required, date-time)

Example:

```json
{
  "object": "segment",
  "id": "seg_01k7c8m4q2f3e9v6t5r1n0p8yz",
  "name": "Pro customers",
  "filter": {
    "version": 1,
    "match": "all",
    "conditions": [
      {
        "field": "property",
        "key": "plan",
        "op": "eq",
        "value": "pro"
      },
      {
        "match": "any",
        "conditions": [
          {
            "field": "email",
            "op": "ends_with",
            "value": "@acme.com"
          },
          {
            "field": "audience",
            "op": "in",
            "audience_id": "aud_01k7c8m4q2f3e9v6t5r1n0p8yz"
          }
        ]
      }
    ]
  },
  "created_at": "2026-10-10T12:00:00.000Z",
  "updated_at": "2026-10-10T12:00:00.000Z"
}
```

## Errors

- `400`: The body is not valid JSON (`invalid_json`). Also when the `Coss-Version` header names an unknown API version (`invalid_api_version`).
- `401`: The API key is missing, invalid, revoked or expired (`authentication_error`).
- `403`: The API key lacks the permission this endpoint needs (`permission_error`), or its organization is suspended (`organization_suspended`).
- `413`: The request body is larger than 5 MB (`payload_too_large`).
- `415`: The body is not sent as `application/json` (`unsupported_media_type`).
- `422`: The body failed validation (`validation_error`), the filter names an unknown property, audience or topic or uses an operator that doesn't suit the property's type (`invalid_filter`, `param` names the condition), or the name is taken (`name_taken`).
- `429`: Too many requests with this API key (`rate_limited`), or too many requests with invalid keys from this address (`too_many_failed_authentications`). Retry after `Retry-After` seconds. Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the limit is fully restored).
- `500`: Unexpected server error (`api_error` / `internal_error`).
- `503`: The API key could not be verified right now; retry (`service_unavailable`).