Send your first email in two minutes

Install the SDK, drop in your key, and send. The same call handles transactional and broadcast email — there's no second product to learn.

npm install @macromail/sdk

import { MacroMail } from '@macromail/sdk';

const mm = new MacroMail(process.env.MACROMAIL_API_KEY);

const { data, error } = await mm.emails.send({
  from: 'You <hello@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Welcome to MacroMail',
  html: '<p>It works — sent over Amazon SES.</p>',
});

A successful send returns { data, error } with a status of queued — not delivered. Delivery is confirmed asynchronously via webhooks and the logs.

Every request authenticates with a secret API key passed as a bearer token:

import { MacroMail } from '@macromail/sdk';

// Pass your secret key. Live keys send real email; test keys
// run the full pipeline but never hit a real inbox.
const mm = new MacroMail('mm_live_xxxxxxxxxxxxxxxxxxxx');

// Or over the wire — every request is authenticated with a
// bearer token in the Authorization header:
//   Authorization: Bearer mm_live_xxxxxxxxxxxxxxxxxxxx

mm.emails.send() (or POST /v1/emails) takes the fields below and returns { data, error }. It never throws on an expected failure — inspect error instead. A successful call returns status queued; delivery is confirmed later.

Add a domain with POST /v1/domainsand we return the exact records to publish at your DNS provider. We check them live — there's no vanity score. Once all five are green, you can send.

The three DKIM tokens are unique per domain and shown in your dashboard when you add it. Keep DMARC at p=none until your reports look clean, then move to quarantine and reject.

A small, predictable REST surface. Base URL https://api.macromail.dev. Every response is JSON and every endpoint is authenticated.

Example — send an email

A send returns the new email's id and a queued status immediately.

// Request — POST /v1/emails
{
  "from": "Acme <hello@acme.com>",
  "to": ["user@example.com"],
  "subject": "Welcome to Acme",
  "html": "<p>You're in.</p>"
}

// Response — 200 OK
{
  "id": "em_2b1f9c7a4d3e",
  "status": "queued",
  "created_at": "2026-06-28T17:04:11Z"
}

Errors come back in the error half of { data, error } with a stable name, an HTTP status, and a human-readable message. Branch on the name, not the prose.

Register an endpoint with POST /v1/webhooks and we'll POST a JSON event for each delivery milestone. Every payload is signed with your webhook secret so you can verify it came from us, and failed deliveries are retried with exponential backoff.

Verify the MacroMail-Signature header against the raw request body before trusting an event. Return a 2xx quickly; anything else is treated as a failure and retried.

MacroMail ships a first-class MCP server. Connect it to Claude, Cursor, or Windsurf and your agent can create API keys, verify domains, and send test email without leaving the editor. Install it in one line:

npx @macromail/mcp install