MailBlastr Skill

The MailBlastr skill packages MailBlastr's official recommendations for sending email so an AI coding agent can wire up reliable sends without guessing at the API. It gives the agent a streamlined recipe for single and batch sends, complete with error handling and retry logic.

A "skill" here is a set of instructions and patterns you drop into your agent's context (for example, a SKILL.md file in your repo, or a tool definition your agent reads). When a task involves sending email, the agent follows the skill's recipe instead of inventing its own.

How to give an agent this skill

This is a skill *pattern*, not a package to install — capture the recipe below as a SKILL.md (or equivalent context file) in your repo and load it into your agent's context. It builds on primitives that already exist: the `mailblastr` Node SDK, the `mailblastr-mcp` MCP server, and the plain JSON Emails API over native HTTP.

What it gives your agent

• Single and batch sending — send one email via POST /emails, or up to 100 in a single POST /emails/batch request.
• Built-in error handling and retry logic — retry transient failures (network errors, 5xx, rate limits) with exponential backoff, and surface validation errors without retrying.
• Idempotency-key support — attach an Idempotency-Key header so a retried send is processed only once. See Idempotency keys.
• Works in any language — the recipe is built on plain HTTP against https://api.mailblastr.com, so it applies whether the agent uses the official `mailblastr` Node SDK or raw fetch/curl/requests.
• Automatic activation — when a task needs email, the agent reaches for the skill instead of hand-rolling a request.

The core recipe

At its heart the skill instructs the agent to authenticate with a Bearer API key (the mb_ key from the dashboard) and POST a JSON body to the Emails API. In Node, the official `mailblastr` SDK wraps this; in any other language the agent makes the same request over native HTTP. A minimal send the agent would produce looks like this:

curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8f3a9c1e-2b4d-4e6f-9a1b-c2d3e4f5a6b7' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "subject": "Hello from your agent",
    "html": "<p>Sent through the MailBlastr skill.</p>"
  }'

Batching

When the agent has many distinct messages to send, the skill prefers POST /emails/batch (a JSON array of up to 100 email objects) over a loop of single sends. Every item is validated before any is sent — see Batch sending.