DocumentationAPI ReferenceKnowledge Base
Getting Started

Quickstart

Send your first email with the MailBlastr API in a few minutes.

Prerequisites

  1. A verified domain — add one under Domains and publish its DNS records. (guide)
  2. An API key — create one under API Keys. It starts with mb_ and is shown once. (guide)

Install the SDK

Using Node.js? Install the official `mailblastr` SDK — the Node.js examples throughout these docs use it. From any other language, call the REST API directly (see the cURL / Python / other tabs in each example).

npm install mailblastr

Send an email

Replace mb_xxxxxxxxx with your API key and use a from address on your verified domain.

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>Your first email 🎉</p>"
});
console.log({ data, error });

Response

A successful send returns the email id you can use to retrieve the email or correlate webhook events.

{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}
If you get validation_error about the domain not being verified, finish the DNS verification first — emails can only be sent from a verified domain you own (or a subdomain of one).

Test addresses

To simulate delivery events without sending to a real inbox (and without damaging your domain reputation), send to one of these reserved test recipients:

AddressSimulates
delivered@example.comA successful delivery.
bounced@example.comA hard bounce.
complained@example.comA spam complaint.
suppressed@example.comA recipient on the suppression list.

Avoid duplicates with an idempotency key

To safely retry a send without delivering the same email twice, pass an Idempotency-Key header. A repeated request with the same key within the window returns the original result instead of sending again.

  • Must be unique per logical request.
  • Keys expire after 24 hours.
  • Maximum length 256 characters.
  • Recommended pattern: <event-type>/<entity-id> — for example welcome-user/123456789.
curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-user/123456789' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Hello from MailBlastr",
    "html": "<p>Your first email 🎉</p>"
  }'

Next steps