API Reference

Send an email

POST /emails — send a single transactional email.

POST/emails

Send a single email from a verified domain. The from address must belong to a domain you have verified; provide at least one of html or text. Returns the created email's id.

Pass an optional Idempotency-Key header to make retries safe — see Idempotency keys.

Headers

Authorizationstringrequired

Bearer API key, e.g. Bearer mb_xxxxxxxxx.

Idempotency-Keystringoptional

Optional unique key so a retried request is processed only once (remembered 24h).

Body parameters

fromstringrequired

Sender address on a verified domain. Accepts Name <addr@domain.com> or a bare address.

tostring | string[]required

Recipient address(es). Between 1 and 50 recipients.

subjectstringrequired

The email subject line.

htmlstringoptional

HTML body. Provide html or text (or both). 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. Provide text or html (or both).

preview_textstringoptional

Inbox preview text (preheader) shown next to the subject in the recipient's inbox list. Injected as a hidden element at the top of the HTML body — never visible in the opened email, and excluded from the plain-text part. Max 150 characters.

ccstring | string[]optional

Carbon-copy recipient(s). Up to 50.

bccstring | string[]optional

Blind carbon-copy recipient(s). Up to 50.

reply_tostring | string[]optional

Reply-To address(es).

headersobjectoptional

Map of custom MIME header name → value. See Custom headers.

attachmentsobject[]optional

Files to attach (max 40MB per email, after Base64 encoding). Each item is { filename, content | path, content_type, content_id }. See Attachments.

tagsobject[]optional

Custom data as key/value pairs: { name, value }. See Tags.

scheduled_atstringoptional

Schedule the email to be sent later. Natural language (e.g. in 1 min) or ISO 8601 (e.g. 2026-08-05T11:52:01.858Z). See Schedule email.

topic_idstringoptional

Topic ID for subscription handling. Each to/cc/bcc address is checked against the topic: recipients who are unsubscribed from the topic are skipped (removed from the recipient lists) and the message is sent to the rest. If every to recipient is skipped, the request is rejected with a validation_error. Addresses that are not contacts are always kept. An unknown topic_id returns a validation_error.

templateobjectoptional

Send using a published template instead of inline body: { id, variables }. id is the template id or alias; variables is an object of key/value pairs. When a template is set you cannot also send html/text; from, subject, and reply_to in the payload take precedence over the template defaults.

attachments[] properties

filenamestringoptional

Name of the attached file.

contentstringoptional

Content of the attached file, passed as a Base64 string. Provide content or path.

pathstringoptional

URL where the attachment file is hosted; fetched at send time. Provide path or content.

content_typestringoptional

Content type for the attachment. Derived from filename when not set.

content_idstringoptional

Embeds the file as an inline image: reference it in your HTML via <img src="cid:...">.

tags[] properties

namestringrequired

The name of the email tag. ASCII letters (a–z, A–Z), numbers (0–9), underscores, or dashes only; max 256 characters.

valuestringrequired

The value of the email tag. ASCII letters (a–z, A–Z), numbers (0–9), underscores, or dashes only; max 256 characters.

The Idempotency-Key header should be unique per API request, has a maximum length of 256 characters, and expires after 24 hours.

Request

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@example.com"],
  "subject": "Hello from MailBlastr",
  "html": "<p>It works!</p>"
});
console.log({ data, error });

Response

{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}

Errors

Returns missing_required_field if from, to, or subject is missing; validation_error if neither html nor text is provided, if to is outside 1–50 recipients, or if the from domain is not verified; invalid_from_address / invalid_to_address for malformed addresses; and 409 concurrent_idempotent_requests if a request with the same in-flight Idempotency-Key is already processing. See the error reference.