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. Cannot be more than 30 days in the future.

schedule_timezonestringoptional

Optional. IANA timezone name (e.g. America/New_York) the scheduled_at wall-clock time is interpreted in — also the zone daily batches roll over in. A scheduled_at that already carries a UTC offset (e.g. a trailing Z) is used as-is. Defaults to your account timezone for batch rollover; while it is unset, an offset-less scheduled_at is read as UTC.

daily_batch_sizenumberoptional

Optional. Send to at most this many recipients per day — an integer between 1 and 100000. Delivery continues the next day at the same local time until every contact is reached. Omit (or pass null) to send to everyone at once.

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.