Resources

Examples

Copy-paste recipes for the most common MailBlastr tasks — sending, batching, scheduling, attachments, contacts, and webhooks — using nothing but an HTTP client.

MailBlastr is a plain JSON REST API with official SDKs for Node.js, Ruby, PHP, Python, Go, Rust, Java, and .NET (plus a CLI) — see the install table. Every endpoint page in these docs carries a copyable tab for each of them alongside raw cURL.

The snippets below string those endpoints together into the recipes people ask for most. Swap mb_xxxxxxxxx for your API key and yourdomain.com for a verified domain.

Send your first email

The smallest useful request — a single transactional email from a verified domain. See Send an email.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

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

Send with an attachment

Inline a file as base64 content, or hand MailBlastr a hosted path URL to fetch at send time. See Attachments.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["user@example.com"],
  "subject": "Your invoice",
  "html": "<p>Invoice attached.</p>",
  "attachments": [
    { "filename": "invoice.pdf", "path": "https://files.example.com/invoice.pdf" }
  ]
});
console.log({ data, error });

Schedule for later

Pass an ISO 8601 scheduled_at to hold an email until a future time. It can be rescheduled or canceled while still pending. See Schedule email.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["user@example.com"],
  "subject": "Your weekly digest",
  "html": "<p>Here is what you missed.</p>",
  "scheduled_at": "2026-06-30T09:00:00Z"
});
console.log({ data, error });

Send a batch

Deliver up to 100 distinct emails in one request by POSTing a JSON array to POST /emails/batch. Every item is validated before any email is sent. See Batch sending.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.batch.send([
  { "from": "Acme <hello@yourdomain.com>", "to": ["a@example.com"], "subject": "Hi A", "html": "<p>Hello A</p>" },
  { "from": "Acme <hello@yourdomain.com>", "to": ["b@example.com"], "subject": "Hi B", "html": "<p>Hello B</p>" }
]);
console.log({ data, error });

Retry safely with an idempotency key

When a network blip leaves you unsure whether a send went through, retry with the same Idempotency-Key — MailBlastr processes it once and replays the original response. See Idempotency keys.

curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-12345' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["user@example.com"],
    "subject": "Receipt",
    "html": "<p>Thanks!</p>"
  }'

Add a contact to an audience

Grow a marketing list by creating a contact inside an audience. Contacts are the recipients of campaigns.

import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.contacts.create({
  audienceId: 'aud_123',
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace"
});
console.log({ data, error });

Verify and handle a webhook

Subscribe to delivery events so your app reacts to bounces, complaints, opens, and clicks as they happen. Every payload is signed — verify the signature before trusting it. See Webhooks.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Express handler — req.body is the raw request buffer
app.post('/webhooks/mailblastr', (req, res) => {
  const signature = req.header('MailBlastr-Signature');
  const expected = createHmac('sha256', process.env.MAILBLASTR_WEBHOOK_SECRET)
    .update(req.body) // raw bytes, not parsed JSON
    .digest('hex');

  const ok = signature && timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
  if (!ok) return res.status(401).end();

  const event = JSON.parse(req.body.toString());
  if (event.type === 'email.bounced') {
    // the recipient was auto-suppressed — update your own records
  }
  res.status(200).end();
});

Always compute the signature over the raw request body. Re-serializing parsed JSON can reorder keys or change whitespace and break verification.

More recipes

The same endpoints cover the full set of common email use-cases. Each is a plain HTTP request you can build in any language — no framework-specific package required.

Use case	How
Basic send	POST a single email to `/emails` with `from`, `to`, `subject`, and `html` or `text`.
Batch send	POST a JSON array (up to 100) to `/emails/batch`.
Attachments	Add an `attachments` array with base64 `content` or a hosted `path` URL — see Attachments.
Inline images (CID)	Reference an attachment from your HTML via `cid:` and set the attachment's `content_id` — see Attachments.
Templates	Send a stored template by `template_id` with `template_variables` instead of inline `html` — see Templates.
Scheduling	Pass an ISO 8601 or natural-language `scheduled_at` to hold the email for later delivery — see Schedule email.
Idempotency	Send an `Idempotency-Key` header to deduplicate retries — see Idempotency keys.
Contact form	Take form input on your backend and POST one (or a batch of) email(s) to MailBlastr.
Audiences & contacts	Create and manage list members under `/audiences` and their contacts.
Domains	Create and verify sending domains via `/domains`.
Double opt-in	On signup, send a confirmation email with a tokenized link; only add the contact once they click it.
Webhooks	Subscribe to delivery events and verify each signed payload — see Webhooks.
Prevent threading (Gmail)	Vary the `subject` or set custom `headers` (e.g. a unique `X-Entity-Ref-ID`) so Gmail doesn't collapse messages into one thread.

Where to go next

Browse the full Send an email reference for every body field (cc, bcc, reply_to, headers, tags).
Set up a sending domain and DNS in Domains.
Send marketing email to a list with Campaigns.
See what is and isn't available yet in the roadmap.