CLI — MailBlastr Docs

CLI

Drive MailBlastr from the terminal — there is no dedicated CLI, but the API is curl-friendly.

MailBlastr does not ship a dedicated command-line tool. Because the API is a plain JSON REST API, the terminal you already have — curl plus jq — covers the full surface, and it works the same in scripts, CI/CD pipelines, and one-off debugging sessions.

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://api.mailblastr.com/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://api.mailblastr.com/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@example.com"],
    "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@example.com"],
    subject: "Hello World",
    html: $html
  }' | curl -X POST 'https://api.mailblastr.com/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://api.mailblastr.com/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "from": "Acme <hello@yourdomain.com>", "to": ["delivered@example.com"], "subject": "Hi", "text": "Hello" }' \
  | jq -r '.id'

# List verified domains by name
curl -s 'https://api.mailblastr.com/domains' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  | jq -r '.data[] | select(.status == "verified") | .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://api.mailblastr.com/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://api.mailblastr.com/emails' \
        -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
        -H 'Content-Type: application/json' \
        -d '{
          "from": "Acme <hello@yourdomain.com>",
          "to": ["team@example.com"],
          "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://api.mailblastr.com/emails' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "from": "Acme <hello@yourdomain.com>", "to": ["delivered@example.com"], "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

MailBlastr groups its API around resources, and each one maps directly to an HTTP endpoint you can drive with curl. The table below lists every resource, the actions it supports, and the endpoint each corresponds to.

Resource	Actions	MailBlastr endpoint
`emails`	`send`, `batch`, `list`, `get`, `cancel`, `update`	`/emails`, `/emails/batch`
`domains`	`create`, `list`, `get`, `verify`, `update`, `delete`	`/domains`
`api-keys`	`create`, `list`, `delete`	`/api-keys`
`campaigns`	`create`, `list`, `get`, `send`, `update`, `delete`	`/campaigns`
`contacts`	`create`, `list`, `get`, `update`, `delete` (plus segment/topic membership)	`/audiences/:id/contacts`
`segments`	`create`, `list`, `get`, `contacts`, `delete`	Segments
`topics`	`create`, `list`, `get`, `update`, `delete`	Topics
`templates`	`create`, `list`, `get`, `update`, `publish`, `duplicate`, `delete`	Templates
`logs`	`list`, `get`	Logs
`webhooks`	`create`, `list`, `get`, `update`, `delete`	`/webhooks`
`automations`	`create`, `list`, `get`, `update`, `stop`, `delete` (plus `runs`)	Automations
`events`	`create`, `send`, `list`, `get`, `update`, `delete`	Events

Authentication is the same everywhere: a mb_-prefixed key, supplied via an environment variable or a CI secret. Output is JSON, so jq works the same across every endpoint. For the full HTTP surface, see the API reference.