# Email Bump CLI

> The `emailbump` command line: every command maps to one REST endpoint and prints the API's JSON verbatim. Built for scripts and AI agents as much as for humans, with confirmation gates on anything irreversible.

**Canonical page:** [https://emailbump.com/cli](https://emailbump.com/cli)

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/danest/emailbump-cli/main/install.sh | sh
```

Installs to `~/.local/bin` (override with `EMAILBUMP_INSTALL_DIR`). macOS (Apple Silicon and Intel) and Linux (x86_64 and aarch64, static musl so any distro works). On Windows, take the .zip from the releases page and put `emailbump.exe` on your PATH. Tarballs: [github.com/danest/emailbump-cli/releases](https://github.com/danest/emailbump-cli/releases). Update by re-running the installer.

## Auth

The easy path is `emailbump login`: the browser opens `emailbump.com/activate` with a pairing code, the user clicks Authorize and chooses the key's scope — **one project** (works only there) or **all access** (provisions workspaces/projects and can act in any project the user admins). One key model, two scopes. The credential is stored in `~/.config/emailbump/credentials.json` (0600). Run `emailbump login` again any time to switch workspace or grant; `emailbump logout` removes it; `emailbump whoami` shows what is stored. For CI/servers set `EMAILBUMP_API_KEY` instead — flag/env always take precedence over the stored credential. With an all-access key and several projects, name the project with `--project <uuid>` (or `EMAILBUMP_PROJECT`) — with exactly one project it's auto-selected; project-scoped keys need nothing. Override the API host with `--base-url` or `EMAILBUMP_BASE_URL` (default `https://emailbump.com/api`).

## Quickstart

```bash
emailbump limits
emailbump emails:send --from 'Acme <hi@updates.acme.com>' --to you@example.com \
  --subject 'Your receipt' --html '<p>Thanks, {{ contact.first_name }}!</p>'
emailbump contacts:list --search jane
emailbump campaigns:create --data '{"name":"Launch","subject":"We are live","segment_id":"...","html":"<p>...</p>"}'
emailbump campaigns:send <id>          # shows the campaign and refuses — review first
emailbump campaigns:send <id> --yes    # actually sends
emailbump api GET /v1/limits           # escape hatch for any endpoint
```

`you@example.com` above is a placeholder, not a test inbox. Sending to `example.com` — or to `example.net`, `example.org`, `.test`, `.invalid`, `.localhost`, `.local` — is refused with a 400. Those domains accept no mail (`example.com` publishes a null MX record saying so), every message to one hard-bounces, and the bounce rate is measured per sending account. Substitute a mailbox you control before running these.

## Conventions

- Output is always JSON; errors go to stderr as JSON with the HTTP status and exit code 1.
- Sends and deletes require `--yes`. Without it the command prints a `confirmation_required` envelope and exits with code 3; `campaigns:send` fetches the campaign first so the audience, subject, and from address can be reviewed.
- `--data '{json}'` carries request bodies; convenience flags override its fields.

## Command groups

Sending (`emails:send`, `limits`) · Contacts (`contacts:list/create/get/update/delete/subscribe/unsubscribe`, `contacts:verify` — bounce-risk check before importing a list) · Events (`events:track`) · Campaigns (`campaigns:list/create/get/update/send`, A/B `variants:*`, `ab`, `ab:winner`) · Flows (`flows:list/create/get/update/delete/test/activate/pause/enroll/enrollments`) · Inbound (`inbound:list/get/attachment/address/forward/reply/stream`, `inbound:rules:*`) · Lists (`lists:*`) · Segments (`segments:list/get`) · Templates (`templates:*`) · Domains (`domains:list/add/check/dns-check/delete`, `domains:dkim:key-length`, `domains:tracking:on/off`) · Account (`workspaces:*`, `projects:create`, `projects:keys:create`, `projects:domains:add/verify/dns-check/delete`, `projects:domains:dkim:key-length`) · `api METHOD /v1/path` escape hatch.

## Related

- [MCP server](https://emailbump.com/mcp.md) — the same binary serves Model Context Protocol clients via `emailbump mcp`.
- [Agent skills](https://emailbump.com/agent-skills.md) — teach coding agents these workflows.
- [API reference](https://emailbump.com/docs/api-reference.md) — the REST API this wraps.