API Reference

Create campaign

POST /campaigns — create a draft campaign against a sending domain.

POST/campaigns

Creates a draft campaign. The domain selects the recipients — the campaign sends to that domain’s contact pool — and the from address must be on a verified domain (it does not have to match domain). You must supply html, text, or both. Returns the new campaign id.

Body parameters

domainstringrequired

The sending domain whose contacts receive the campaign (one of your domains). Orthogonal to from — the from address may be on a different verified domain. Passing audience_id is no longer accepted — pass domain.

fromstringrequired

Sender address on a verified domain, e.g. Acme <news@yourdomain.com>.

subjectstringrequired

Subject line. Supports merge tags.

htmlstringoptional

HTML body. Required if text is omitted. Supports merge tags. Markdown-style [text](url) links and bare URLs (https://… / www.…) in the body text are converted to tracked hyperlinks automatically at send time; content already inside <a> tags, attribute values, and <pre>/<code> blocks is left untouched.

textstringoptional

Plain-text body. Required if html is omitted. Supports merge tags.

reply_tostring | string[]optional

Optional Reply-To address. For multiple addresses, send an array of strings.

namestringoptional

The friendly name of the campaign. Only used for internal reference.

preview_textstringoptional

Optional preview text shown in the inbox after the subject line. Supports merge tags (rendered per recipient). Max 150 characters. Follow-ups do not inherit it.

segment_idstringoptional

Narrow the send to a segment of the domain’s contacts. The segment must belong to the same domain.

topic_idstringoptional

Gate the send on topic subscription — only recipients subscribed to this topic receive the campaign.

sendbooleanoptional

When true, send (or schedule) the campaign immediately after create, without a separate POST /campaigns/:id/send call.

scheduled_atstringoptional

Used with send: true. ISO 8601 timestamp or natural-language phrase (e.g. in 1 hour). If in the future the campaign is scheduled rather than sent now.

recurrencestringoptional

Make the campaign repeat on a cadence: daily, weekly, or monthly.

recurrence_everynumberoptional

Number of periods between recurring sends (1–365). Defaults to 1.

ab_testobjectoptional

A/B test configuration. Set enabled: true and supply at least one variant-B field (subject_b, html_b, text_b). test_pct (1–100, default 20) controls the split; metric (open, click, or reply, default open) picks the winner; eval_hours (1–168) sets how long to run the test before evaluating and sending the winner.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.campaigns.create({
  "domain": "yourdomain.com",
  "from": "Acme <news@yourdomain.com>",
  "subject": "What's new in June",
  "html": "<p>Hi {{FIRST_NAME}}!</p>",
  "name": "June newsletter"
});
console.log({ data, error });

Response

{
  "id": "8f5c2a1e-7b3d-4f9a-9c12-2e6d4a7b8c90"
}

Errors: missing_required_field if from, subject, or domain is absent; validation_error if neither html nor text is provided, the domain is not yours, or audience_id is passed (no longer accepted — pass domain); invalid_from_address if from is malformed.