AI Onboarding

If you are building with AI, MailBlastr offers several resources to improve your experience — an MCP server, agent-readable docs, an email Chat SDK, and battle-tested best practices for production sends. This page is the jumping-off point.

Prerequisite: create an API key

We require a human to create a MailBlastr account. Once you have an account, create an API key — it looks like mb_xxxxxxxxx. With a key, your agent can send email and manage most of your account over the API.

MailBlastr MCP server

MCP is an open protocol that standardizes how applications provide context to LLMs. Among other benefits, it gives LLMs tools to act on your behalf. The MailBlastr MCP server is published on NPM as mailblastr-mcp and covers the full API surface. Add it to any supported MCP client:

{
  "mcpServers": {
    "mailblastr": {
      "command": "npx",
      "args": ["-y", "mailblastr-mcp"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}

See MCP Server for install instructions for Cursor, Codex, Claude Desktop, Windsurf, and more.

MailBlastr docs for agents

You can give your agent current, context-aware docs in two ways:

1. Markdown docs — every doc page has a Markdown version. Append .md to any page URL, e.g. https://mailblastr.com/docs/ai/onboarding.md.
2. MCP docs server — for a structured approach using MCP tools, point your client at the docs MCP endpoint so your agent can search the docs as tools rather than fetching a single large file.

Email skills for agents

Skills give AI agents specialized knowledge for specific tasks. These are reference *patterns* you capture as a SKILL.md (or equivalent context file) in your repo — they build on the `mailblastr` SDK, the `mailblastr-mcp` MCP server, webhooks, and native HTTP, so there is nothing extra to install:

Conversational email (Chat SDK pattern)

You can turn email into a two-way communication channel for an agent: send replies with the `mailblastr` SDK or POST /emails, receive inbound mail through webhooks (email.received), and thread conversations with standard In-Reply-To/References headers. The Chat SDK guide shows how to wire this up as a Vercel Chat SDK adapter, including card emails, attachments, and proactive outreach.

Quick start: sending email from an agent

MailBlastr provides two endpoints for sending. Pick the right one for the job:

Choose batch when you are sending 2+ distinct emails at once and want to reduce API calls. Choose single when you are sending one email, the email needs attachments, the email needs to be scheduled, or different recipients need different timing.

Best practices (critical for production)

Always implement these for production email sending.

Idempotency keys — prevent duplicate emails when retrying failed requests. Pass a unique Idempotency-Key header per logical send; a retry with the same key replays the original response instead of sending again. See Idempotency keys.

Error handling — map status codes to actions:

Retry strategy — use exponential backoff (1s, 2s, 4s…), cap at 3–5 retries, only retry 429 and 500, and always send the same idempotency key on a retry.

Single send parameters

Minimal single send

curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-email/user-123' \
  -d '{
    "from": "Acme <onboarding@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Hello World",
    "html": "<p>Email body here</p>"
  }'

Minimal batch send

Because a batch is validated atomically — one invalid item rejects the whole request — pre-validate every email (required fields, address format, and a size of 1–100) before sending.

• No attachments — use single sends for emails with attachments.
• No scheduling — use single sends for scheduled emails.
• Atomic — if one email fails validation, the entire batch fails.
• Max 100 emails per request.
• Max 50 recipients per individual email in the batch.

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": "Order Shipped",   "html": "<p>Your order has shipped!</p>" },
  { "from": "Acme <hello@yourdomain.com>", "to": ["b@example.com"], "subject": "Order Confirmed", "html": "<p>Your order is confirmed!</p>" }
]);
console.log({ data, error });