Mailbase CLI
The mailbase command-line tool: every Mailbase capability as a predictable command, with JSON output and stable exit codes, built for coding agents and scripts.
Install and sign in
The CLI has no AI in it: it is a thin client over the REST API that your agent (Claude Code, Codex, Cursor…) or your scripts drive.
mailbase login opens your browser. Sign in, choose the workspace the CLI may use and the permissions you give it, then approve. The CLI receives its own session and renews it by itself: there is no API key to create, copy or paste, and nobody — you or your agent — ever sees a token. The session appears under connected apps in Settings, where you can revoke it.
No browser on that machine (an agent in a sandbox, a server over SSH)? mailbase login --device prints a short code: open the link on any device, enter the code and approve.
npm i -g mailbase # or run any command with npx mailbase
mailbase login # opens the browser: pick the workspace and permissions
mailbase whoami # who you are, the workspace and the granted permissions
mailbase skill install # teach your coding agent how to use the CLITeach your agent
mailbase skill install writes the mailbase-cli skill where Claude Code (~/.claude/skills) and Codex (~/.agents/skills) load skills from; --agent claude or --agent codex picks one, --scope project installs it in the current repository instead. The skill tells the agent how to discover commands, which flags to always use, when it must stop and ask you, and step-by-step recipes for prospecting, campaigns, replies and sending setup. The Mailbase plugin ships the same skill.
Built for agents
- One group per area: domains, senders, mailboxes, campaigns, templates, audiences, contacts, suppressions, forms, threads, pipeline, workflows, prospecting, pool, drafts, sequence, analytics and more.
- mailbase commands --json lists every command, flag and example in one call; mailbase <group> <command> --help explains one.
- --json prints only the API's JSON on stdout; --quiet prints ids for chaining; --no-input never prompts.
- Anything that emails people or deletes data asks for confirmation in a terminal, and needs --yes when run non-interactively. Without it the command stops with exit code 9 and sends nothing.
- For CI and servers with no person to sign in, set MAILBASE_API_KEY to an API token instead (MAILBASE_API_URL for a self-hosted server).
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected error |
| 2 | Usage error: unknown command or flag, bad or missing value |
| 3 | Not logged in, or the API token is invalid |
| 4 | Not found |
| 5 | Permission denied: missing scope or workspace role |
| 6 | Refused by Mailbase's rules, or a conflict |
| 7 | Rate limited (Retry-After is printed) |
| 8 | Network or server error |
| 9 | Confirmation required: re-run with --yes once the user agreed |
Examples
mailbase prospecting naf boulang --json
mailbase prospecting targets create --name "Bakeries Lyon" --naf-codes 10.71C --departments 69 --json
mailbase pool facets --target <target-id> --json
mailbase pool archive --target <target-id> --status found --all --yes
mailbase drafts list --json
mailbase campaigns create --name "October news" --subject "What's new" --body-file news.mjml --audience <audience-id>
mailbase campaigns test <campaign-id> --to me@example.com --yes
mailbase campaigns launch <campaign-id> # asks first