# 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.

```bash
export MAILBLASTR_API_KEY=mb_xxxxxxxxx

# Reuse it in any request
curl 'https://api.mailblastr.com/domains' \
  -H "Authorization: Bearer $MAILBLASTR_API_KEY"
```

> **Warning:** 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](https://www.mailblastr.com/docs/api/emails-send) — provide the body inline, or read it from a file.

```bash
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:

```bash
# 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.

```bash
# 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](https://www.mailblastr.com/docs/api/emails-batch). Use `@filename` to send the file as the request body.

```bash
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:

```yaml
# 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:

```bash
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
```

> **Note:** See the [error reference](https://www.mailblastr.com/docs/api/errors) 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`](https://www.mailblastr.com/docs/api/emails-send), [`/emails/batch`](https://www.mailblastr.com/docs/api/emails-batch) |
| `domains` | `create`, `list`, `get`, `verify`, `update`, `delete` | [`/domains`](https://www.mailblastr.com/docs/domains/managing) |
| `api-keys` | `create`, `list`, `delete` | [`/api-keys`](https://www.mailblastr.com/docs/api-keys/overview) |
| `campaigns` | `create`, `list`, `get`, `send`, `update`, `delete` | [`/campaigns`](https://www.mailblastr.com/docs/campaigns/managing) |
| `contacts` | `create`, `list`, `get`, `update`, `delete` (plus segment/topic membership) | [`/audiences/:id/contacts`](https://www.mailblastr.com/docs/audiences/contacts) |
| `segments` | `create`, `list`, `get`, `contacts`, `delete` | [Segments](https://www.mailblastr.com/docs/audiences/overview) |
| `topics` | `create`, `list`, `get`, `update`, `delete` | [Topics](https://www.mailblastr.com/docs/audiences/overview) |
| `templates` | `create`, `list`, `get`, `update`, `publish`, `duplicate`, `delete` | [Templates](https://www.mailblastr.com/docs/templates/overview) |
| `logs` | `list`, `get` | [Logs](https://www.mailblastr.com/docs/api/errors) |
| `webhooks` | `create`, `list`, `get`, `update`, `delete` | [`/webhooks`](https://www.mailblastr.com/docs/webhooks/overview) |
| `automations` | `create`, `list`, `get`, `update`, `stop`, `delete` (plus `runs`) | [Automations](https://www.mailblastr.com/docs/campaigns/managing) |
| `events` | `create`, `send`, `list`, `get`, `update`, `delete` | [Events](https://www.mailblastr.com/docs/webhooks/overview) |

> **Note:** 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](https://www.mailblastr.com/docs/api/emails-send).