# 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`, or `unsubscribed`. |
| `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`. |

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('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 "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

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

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

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

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

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

**Go**

```go
client := mailblastr.NewClient("mb_xxxxxxxxx")

params := &mailblastr.CreateSegmentRequest{
    Domain: "yourdomain.com",
    Name:   "VIP customers",
}
segment, err := client.Segments.Create(params)
```

**Rust**

```rust
let mb = Mailblastr::new("mb_xxxxxxxxx");

let segment = CreateSegmentOptions::new("yourdomain.com", "VIP customers");
let _created = mb.segments.create(segment).await?;
```

**Java**

```java
Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

CreateSegmentRequest request = CreateSegmentRequest.builder()
    .domain("yourdomain.com")
    .name("VIP customers")
    .build();
mailblastr.segments().create(request);
```

**.NET**

```csharp
IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");

var resp = await mailblastr.SegmentCreateAsync(new SegmentCreateOptions
{
    Domain = "yourdomain.com",
    Name = "VIP customers",
});
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/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
mailblastr segments create \
  --domain 'yourdomain.com' \
  --name 'Gmail subscribers' \
  --filter '{"status":"subscribed","email_contains":"@gmail.com"}'
```

### Response

```json
{
  "object": "segment",
  "id": "seg_9a2f...",
  "audience_id": "aud_3b1c...",
  "name": "Gmail subscribers",
  "filter": { "status": "subscribed", "email_contains": "@gmail.com", "property_filters": [] },
  "created_at": "2026-06-23T10:00:00.000Z",
  "updated_at": "2026-06-23T10:00:00.000Z"
}
```

> **Note:** Errors: `missing_required_field` if `name` or `domain` is absent (passing `audience_id` instead of `domain` is rejected with a `422`); `409` if a segment with the same name already exists on that domain; `validation_error` if `filter.status` is not one of the allowed values, the domain is not yours, or a `property_filters` entry references an unknown or invalid property.