DocumentationAPI ReferenceKnowledge Base
CLI

CLI

Drive MailBlastr from the terminal — the official `mailblastr-cli`, or plain curl.

MailBlastr ships an official command-line tool: npm install -g mailblastr-cli (Node.js 18+) gives you a mailblastr command covering sends, domains, contacts, campaigns, and more — every API reference page includes its CLI invocation in the snippet tabs. To install it and send your first email, start with the CLI Quickstart; the Command surface table below lists every group and subcommand.

Prefer zero install? Because the API is a plain JSON REST API, the terminal you already have — curl plus jq — covers the full surface too, and it works the same in scripts, CI/CD pipelines, and one-off debugging sessions. The rest of this page is the curl cookbook.

Authentication

Keep your API key out of your shell history by exporting it once, then reference it in every request. The key is the same mb_-prefixed key you use everywhere else.

export MAILBLASTR_API_KEY=mb_xxxxxxxxx

# Reuse it in any request
curl 'https://www.mailblastr.com/api/domains' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY"
Never paste a live key directly into a command you'll commit or share. Use an environment variable (or your CI secret store) so the key never lands in shell history or version control.

Send an email

The terminal equivalent of POST /emails — provide the body inline, or read it from a file.

curl -X POST 'https://www.mailblastr.com/api/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@mailblastr.dev"],
    "subject": "Hello World",
    "text": "It works!"
  }'

Send an HTML body straight from a file with @-syntax — handy for templates you maintain on disk:

# Build the JSON with the file's HTML inlined, then send it
jq -n --rawfile html ./welcome.html '{
    from: "Acme <hello@yourdomain.com>",
    to: ["delivered@mailblastr.dev"],
    subject: "Hello World",
    html: $html
  }' | curl -X POST 'https://www.mailblastr.com/api/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @-

Pipe JSON through jq

Every endpoint returns JSON, so jq lets you extract exactly the field you need — the email id, a list of domains, an event log.

# Capture just the new email id
curl -s -X POST 'https://www.mailblastr.com/api/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "from": "Acme <hello@yourdomain.com>", "to": ["delivered@mailblastr.dev"], "subject": "Hi", "text": "Hello" }' \
  | jq -r '.id'

# List sendable domains by name — a domain can send while its status is any
# of verified, partially_verified or partially_failed
curl -s 'https://www.mailblastr.com/api/domains' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  | jq -r '.data[] | select(.status | test("^(verified|partially_verified|partially_failed)$")) | .name'

Send a batch from a file

Keep an array of email objects in a JSON file and POST it to POST /emails/batch. Use @filename to send the file as the request body.

curl -X POST 'https://www.mailblastr.com/api/emails/batch' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d @emails.json \
  | jq '.data'

Use in CI/CD

Store your key as a CI secret and read it from the environment — no interactive login step is needed. For example, sending a deploy notification from GitHub Actions:

# GitHub Actions
env:
  MAILBLASTR_API_KEY: ${{ secrets.MAILBLASTR_API_KEY }}
steps:
  - run: |
      curl -X POST 'https://www.mailblastr.com/api/emails' \
        -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
          "from": "Acme <hello@yourdomain.com>",
          "to": ["delivered@mailblastr.dev"],
          "subject": "Deploy complete",
          "text": "Version ${{ github.sha }} deployed."
        }'

Handle errors in scripts

MailBlastr returns a structured error envelope with a name and message, and a non-2xx HTTP status. Capture the status code so a failed send fails your script:

status=$(curl -s -o /tmp/out.json -w '%{http_code}' -X POST 'https://www.mailblastr.com/api/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "from": "Acme <hello@yourdomain.com>", "to": ["delivered@mailblastr.dev"], "subject": "Hi" }')

if [ "$status" -ge 400 ]; then
  echo "Send failed:" >&2
  jq -r '.message' /tmp/out.json >&2
  exit 1
fi
See the error reference for the full envelope and every error name MailBlastr can return.

Command surface

The official CLI mirrors the API one command group per resource — mailblastr <resource> <action>. The table below lists every group, its subcommands, and the docs for what it drives. Run mailblastr <resource> --help for the flags of any one of them, and see the CLI Quickstart to install it and send your first email.

Command groupSubcommandsDocs
mailblastr emailssend, batch, get, list, update, cancel, sources, attachments, attachment`/emails`, `/emails/batch`
mailblastr emails receivinglist, addresses, get, attachments, attachment, raw, forward, reply, deleteReceiving
mailblastr domainsadd, get, list, verify, update, mx-check, records-csv, delete, plus dns (detect, cloudflare, godaddy, namecheap) and claim (start, get, verify)Domains
mailblastr contactscreate, list, get, update, delete, add-to-segment, remove-from-segment, segments, topics, set-topics, batch, import, import-uploadContacts
mailblastr contact-propertiescreate, list, get, update, deleteContact properties
mailblastr audiencescreate, list, get, update, delete, import-sheetAudiences
mailblastr segmentscreate, list, get, contacts, update, deleteSegments
mailblastr topicscreate, list, get, update, deleteTopics
mailblastr campaignscreate, send, get, list, update, cancel, stats, engagement, ab, deleteCampaigns
mailblastr templatescreate, get, list, update, duplicate, publish, deleteTemplates
mailblastr automationscreate, get, list, update, add-step, update-step, delete-step, runs, run, stop, ai, deleteAutomations
mailblastr webhookscreate, get, list, update, rotate, test, delete, verifyWebhooks
mailblastr eventssend, create, list, update, deleteCustom events
mailblastr logslist, getLogs
mailblastr pollslist, get`/polls`
mailblastr api-keyslist only — creating, re-scoping and revoking keys are dashboard-only and answer 403 dashboard_only to any API-key callerAPI keys
Authentication is the same for every command that reaches the API: a mb_-prefixed key, supplied via MAILBLASTR_API_KEY, --api-key, or a CI secret. webhooks verify is the exception — it verifies a signature locally, sends nothing, needs no key, and does not accept --api-key. Output is JSON, so jq works the same across every command and every endpoint. For the full HTTP surface, see the API reference.