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

Install the official SDK for your language — Node.js, Python, Ruby, PHP, Go, Rust, Java, .NET, or the CLI. Every install command is listed on SDKs. The Node.js examples throughout these docs use the mailblastr npm package; each example also has tabs for the other packages and a dependency-free cURL tab if you prefer no SDK at all.

npm install mailblastr        # Node.js
pip install mailblastr        # Python
composer require mailblastr/mailblastr   # PHP

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@mailblastr.dev"],
  "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@mailblastr.devA successful delivery.
bounced@mailblastr.devA hard bounce.
complained@mailblastr.devA spam complaint.
suppressed@mailblastr.devA 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 255 characters.
  • Recommended pattern: <event-type>/<entity-id> — for example welcome-user/123456789.
curl -X POST 'https://www.mailblastr.com/api/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@mailblastr.dev"],
    "subject": "Hello from MailBlastr",
    "html": "<p>Your first email 🎉</p>"
  }'

Next steps