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, unsubscribed, or members_only (matches nobody by filter — the segment resolves to its explicitly added contacts only).

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.

filter.engagementobject | nulloptional

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.

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

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.