API Reference

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

namestringrequired

A name for the segment. Unique within the domain; the same name can be reused on other domains.

domainstringrequired

The sending domain whose contacts this segment filters (one of your domains). Passing audience_id is no longer accepted — pass domain.

filter.statusstringoptional

all (default), subscribed, or unsubscribed.

filter.email_containsstringoptional

Optional case-insensitive email substring match.

filter.property_filtersarrayoptional

Optional list of custom-property predicates. Each entry: { key, operator, value? }. Operators: eq, contains, exists. Keys must be registered via POST /contact-properties.

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 });

Response

{
  "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"
}

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.