# Create segment

> POST /segments — save a reusable filter over a sending domain’s contacts.

`POST /segments`

Creates a segment against one of your sending domains. Returns the segment object. Segment names are unique within a domain (a duplicate name returns `409`) but freely reusable across domains — and every domain already carries an auto-created **General** segment matching all of its contacts.

**Body parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | A name for the segment. Unique within the domain; the same name can be reused on other domains. |
| `domain` | string | Yes | The sending domain whose contacts this segment filters (one of your domains). Passing `audience_id` is no longer accepted — pass `domain`. |
| `filter.status` | string | No | `all` (default), `subscribed`, `unsubscribed`, or `members_only` (matches nobody by filter — the segment resolves to its explicitly added contacts only). |
| `filter.email_contains` | string | No | Optional case-insensitive email substring match. |
| `filter.property_filters` | array | No | Optional list of custom-property predicates. Each entry: `{ key, operator, value? }`. Operators: `eq`, `contains`, `exists`. Keys must be registered via `POST /contact-properties`. |
| `filter.engagement` | object | null | No | Object or `null`. An engagement predicate: `{ event, campaign_id }`, where `event` is one of `clicked`, `not_clicked`, `opened`, `not_opened` and `campaign_id` is required whenever `engagement` is set. Pass `null` to clear it. |

**Node.js**

```js
import { SendPing } from 'sendping';

const mb = new SendPing('mb_xxxxxxxxx');

const { data, error } = await mb.segments.create({ "domain": "yourdomain.com", "name": "Gmail subscribers", "filter": { "status": "subscribed", "email_contains": "@gmail.com" } });
console.log({ data, error });
```

**Ruby**

```ruby
require "sendping"

SendPing.api_key = "mb_xxxxxxxxx"

SendPing::Segments.create({
  "domain": "yourdomain.com",
  "name": "Gmail subscribers",
  "filter": {
    "status": "subscribed",
    "email_contains": "@gmail.com"
  }
})
```

**PHP**

```php
<?php
require 'vendor/autoload.php';

use SendPing\SendPing;

$sendping = SendPing::client('mb_xxxxxxxxx');

$sendping->segments->create([
  'domain' => "yourdomain.com",
  'name' => "Gmail subscribers",
  'filter' => [
    'status' => "subscribed",
    'email_contains' => "@gmail.com"
  ]
]);
```

**Python**

```python
import sendping

sendping.api_key = "mb_xxxxxxxxx"

sendping.Segments.create({
  "domain": "yourdomain.com",
  "name": "Gmail subscribers",
  "filter": {
    "status": "subscribed",
    "email_contains": "@gmail.com"
  }
})
```

**Go**

```go
import "github.com/shekhu10/sendping-sdks/sendping-go"

client := sendping.NewClient("mb_xxxxxxxxx")

segment, err := client.Segments.Create(&sendping.CreateSegmentRequest{
    Domain: "yourdomain.com",
    Name:   "Gmail subscribers",
    Filter: &sendping.SegmentFilterInput{
        Status:        "subscribed",
        EmailContains: "@gmail.com",
    },
})
```

**Rust**

```rust
use sendping::{CreateSegmentOptions, SegmentFilterOptions, SegmentStatus, SendPing};

let mb = SendPing::new("mb_xxxxxxxxx");

let params = CreateSegmentOptions::new("yourdomain.com", "Gmail subscribers")
    .with_filter(SegmentFilterOptions::new()
        .with_status(SegmentStatus::Subscribed)
        .with_email_contains("@gmail.com"));
let _segment = mb.segments.create(params).await?;
```

**Java**

```java
import co.sendping.SendPing;
import co.sendping.SendPingResponse;
import co.sendping.requests.CreateSegmentRequest;
import co.sendping.requests.SegmentFilter;

SendPing sendping = new SendPing("mb_xxxxxxxxx");

CreateSegmentRequest request = CreateSegmentRequest.builder()
        .domain("yourdomain.com")
        .name("Gmail subscribers")
        .filter(SegmentFilter.builder()
                .status("subscribed")
                .emailContains("@gmail.com")
                .build())
        .build();

SendPingResponse response = sendping.segments().create(request);
```

**.NET**

```csharp
using SendPing;

ISendPing sendping = SendPingClient.Create("mb_xxxxxxxxx");

var resp = await sendping.SegmentCreateAsync(new SegmentCreateOptions
{
    Domain = "yourdomain.com",
    Name = "Gmail subscribers",
    Filter = new SegmentFilterOptions
    {
        Status = "subscribed",
        EmailContains = "@gmail.com",
    },
});
```

**cURL**

```bash
curl -X POST 'https://www.sendping.co/api/segments' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{ "domain": "yourdomain.com", "name": "Gmail subscribers", "filter": { "status": "subscribed", "email_contains": "@gmail.com" } }'
```

**CLI**

```bash
sendping segments create \
  --domain 'yourdomain.com' \
  --name 'Gmail subscribers' \
  --filter '{"status":"subscribed","email_contains":"@gmail.com"}'
```

### Response

```json
{
  "object": "segment",
  "id": "4c1f8b2e-9a2f-4d71-8f0c-2b5d7e6a1c93",
  "audience_id": "78261eea-8f8b-4381-83c6-79fa7120f1cf",
  "name": "Gmail subscribers",
  "filter": { "status": "subscribed", "email_contains": "@gmail.com", "property_filters": [], "engagement": null },
  "created_at": "2026-06-23T10:00:00.000Z",
  "updated_at": "2026-06-23T10:00:00.000Z"
}
```

> **Note:** Errors (all `422` unless noted): `missing_required_field` if `name` is absent; `validation_error` if `domain` is absent or is not one of your domains, if `audience_id` is passed instead of `domain`, if `filter.status` is not one of the allowed values, if a `property_filters` entry references an unknown or invalid property, or if `filter.engagement` is malformed (a bad `event`, or a missing `campaign_id`); `409` if a segment with the same name already exists on that domain.