Audience

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 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 is a set of predicates, all combined with AND:

Filter

status'all' | 'subscribed' | 'unsubscribed' | 'members_only'optional

Match by subscription status. Defaults to all. members_only (matches nobody by filter — the segment resolves to its explicitly added contacts only).

email_containsstringoptional

Match contacts whose email contains this substring (case-insensitive).

property_filtersarrayoptional

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.

engagementobject | nulloptional

Optional engagement predicate against one campaign: { event, campaign_id }. event is one of clicked, not_clicked, opened, not_opened. null (the default) means no engagement predicate.

Create a segment

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

Preview who matches

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

const { data } = await mb.segments.contacts('4c1f8b2e-9a2f-4d71-8f0c-2b5d7e6a1c93');
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).

await mb.campaigns.create({
  domain: 'yourdomain.com',
  segment_id: '4c1f8b2e-9a2f-4d71-8f0c-2b5d7e6a1c93',
  from: 'Acme <news@yourdomain.com>',
  subject: 'A note for our Gmail folks',
  html: '<p>Hi {{FIRST_NAME}}</p>',
});

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.

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.