# Segments

> Save reusable filters over a sending domain’s contacts and target campaigns at a subset of them.

A **segment** is a saved, reusable filter over the contacts on one of your sending **domains**. Instead of sending a [campaign](https://www.mailblastr.com/docs/campaigns/managing) to a domain’s entire contact pool, you can target a segment — a subset matched by a filter. A segment belongs to exactly one domain: names are unique within a domain but freely reusable across domains, and every domain also carries an auto-created **General** segment that matches all of its contacts.

Segments are for **your own internal organization** — they are never visible to your contacts. Use them to group contacts however makes sense for your sending (by signup source, plan, engagement, email domain, and so on).

## Filters

A segment filter has two parts, combined with AND:

**Filter**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | 'all' | 'subscribed' | 'unsubscribed' | No | Match by subscription status. Defaults to `all`. |
| `email_contains` | string | No | Match contacts whose email contains this substring (case-insensitive). |
| `property_filters` | array | No | Optional list of custom-property predicates combined with AND. Each entry requires a `key` (registered contact property), an `operator` (`eq`, `contains`, or `exists`), and (for `eq`/`contains`) a `value`. Register properties first with `POST /contact-properties`. |

## Create a segment

**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"}'
```

## Preview who matches

List the contacts a segment currently resolves to — useful to sanity-check a filter before sending.

```ts
const { data } = await mb.segments.contacts('seg_9a2f...');
console.log(data.data.length, 'contacts match');
```

## Send a campaign to a segment

Pass `segment_id` when creating a campaign. The campaign then fans out only to the segment’s matching contacts (still excluding anyone unsubscribed, for compliance).

```ts
await mb.campaigns.create({
  domain: 'yourdomain.com',
  segment_id: 'seg_9a2f...',
  from: 'Acme <news@yourdomain.com>',
  subject: 'A note for our Gmail folks',
  html: '<p>Hi {{FIRST_NAME}}</p>',
});
```

> **Note:** For compliance, a campaign never sends to unsubscribed contacts even if a segment’s `status` would include them — the `status` filter is most useful for previewing/auditing, while `email_contains` is what narrows a send.

> **Note:** Include the `{{{MAILBLASTR_UNSUBSCRIBE_URL}}}` merge tag in a segment campaign and MailBlastr automatically replaces it with the correct per-contact unsubscribe link — so opt-outs are handled for you. See [Managing unsubscribed contacts](https://www.mailblastr.com/docs/audiences/unsubscribed).