mailbox API : mailbox CLI

What is it?

The mailbox CLI (mailbox) is a small, self-contained command line tool for the mailbox API (api.mailbox.org). It is a single binary without any runtime dependencies, available for Linux, macOS and Windows. It authenticates with a static API key that you create in the mailbox console.

Installation

The install script detects your operating system and architecture, verifies the checksum and places the binary on your PATH.

Linux / macOS (installs to /usr/local/bin, or ~/.local/bin if that is not writable; override with MAILBOX_INSTALL_DIR):

curl -fsSL https://api.mailbox.org/v1/cli/install.sh | sh

Windows (PowerShell) (installs to %LOCALAPPDATA%\Programs\mailbox and adds it to your user PATH; open a new shell afterwards):

irm https://api.mailbox.org/v1/cli/install.ps1 | iex

Alternatively, download the binary for your platform directly from https://api.mailbox.org/v1/cli/latest/:

Keep the original file name until the checksum is verified, then rename it. Example for Linux (x86_64):

curl -fLO https://api.mailbox.org/v1/cli/latest/mailbox-linux-amd64
curl -fLO https://api.mailbox.org/v1/cli/latest/checksums.txt
sha256sum --ignore-missing -c checksums.txt   # must print "mailbox-linux-amd64: OK"
mv mailbox-linux-amd64 mailbox && chmod +x mailbox
./mailbox --help

On macOS, verify with shasum -a 256 --ignore-missing -c checksums.txt. On Windows (PowerShell), compare the output of (Get-FileHash .\mailbox-windows-amd64.exe -Algorithm SHA256).Hash with the matching line in checksums.txt.

Every release is also available pinned to a specific version, e.g. https://api.mailbox.org/v1/cli/1.2.3/mailbox-linux-amd64, in addition to latest.

Set up the API key

  1. In the mailbox console, open API access and create a new API key. Keep the page open: the complete key is shown only once. The public key ID shown in the key list is not sufficient for the import.

  2. First start the import in your terminal:

    mailbox token import

    The client shows the API endpoint and the local storage location.

  3. Only now copy the key in the mailbox console. (If you copied the key first, copying the command above would replace it in your clipboard.)

  4. Paste the key at the prompt and press Enter. No characters are displayed while you paste. No clipboard tools, echo, prepared key file or Ctrl+D are needed.

If the format is invalid, the client explains the problem and asks again. Ctrl+C cancels without changing an already stored key.

A successful import only confirms the format and the local storage. It does not confirm that the key is valid on the server, its expiry, owner or permissions. These are checked with every API call, for example:

mailbox hello innerworld

Error 493 means that authentication with the API key failed (key deleted, expired or unknown). Check the key in the mailbox console and, if necessary, create and import a new one.

Replacing and managing keys

  • Run mailbox token import again to store a new key. If a key is already stored, the client asks for confirmation; --replace skips this question, as does the global --yes in interactive mode.

  • Replacing a key locally does not revoke the old key. Verify the new key with an API call first, then delete the old key in the mailbox console. Other applications using the old key lose access as well.

  • mailbox status and mailbox whoami only show whether a key is stored locally and its public key ID. They do not prove identity or validity.

  • mailbox token and mailbox token --out FILE export the secret explicitly. Do not put it into logs, tickets or your shell history.

  • One key is stored per configuration. Use separate configurations and stores for different owners or environments.

  • Keys do not rotate automatically.

Scripts and CI

The interactive prompt only appears in a terminal, without --no-interaction and without an explicit key source. File and stdin imports never prompt; an existing key is only replaced with --replace (not with --yes alone). --stdin reads until EOF and is meant for pipes and redirects:

mailbox token import --file ./customer.apikey
mailbox token import --stdin < ./customer.apikey
mailbox token import --file ./replacement.apikey --replace

A key can also be used directly without importing it, preferably from a protected file or stdin:

mailbox --token-file ./customer.apikey account:get <account>
cat ./customer.apikey | mailbox --token-stdin account:get <account>
MAILBOX_TOKEN_FILE=/run/secrets/mailbox-apikey mailbox domain:list <account>

MAILBOX_TOKEN and --token KEY work as well, but passing the secret as an argument exposes it in the process list and shell history. Set only one explicit source at a time. A set key source prevents the interactive prompt; remove old overrides if necessary (unset MAILBOX_TOKEN MAILBOX_TOKEN_FILE, PowerShell: Remove-Item Env:MAILBOX_TOKEN, Env:MAILBOX_TOKEN_FILE -ErrorAction SilentlyContinue). --no-interaction without an explicit source and redirected stdin without --stdin fail with instructions instead of opening a prompt.

Use separate keys for independent purposes so that they can be revoked separately.

Basic usage

mailbox hello innerworld            # first authenticated API call
mailbox account:get <account>
mailbox domain:list <account>
mailbox call <method> --param k=v   # generic JSON-RPC call
mailbox --help                      # list all available commands
mailbox <command> --help            # help for a specific command

The client also supports shell auto-completion for bash, zsh and fish, which is set up automatically on first interactive use (no network access required; disable with MAILBOX_NO_COMPLETION_INSTALL=1). See mailbox completion --help for details.

Uninstallation

  1. Revoke keys you no longer need in the mailbox console. If a key is shared with other applications, consider the impact on them first.

  2. Remove the locally stored key:

    mailbox logout

    mailbox logout only deletes the local store and does not contact the server. It does not revoke the key. External key files, environment secrets and other copies remain untouched.

  3. Remove the binary: /usr/local/bin/mailbox or ~/.local/bin/mailbox (or your MAILBOX_INSTALL_DIR); on Windows %LOCALAPPDATA%\Programs\mailbox, and remove that folder from your user PATH. Also remove the optional mb symlink if you created one.

  4. Remove the shell completion files, if installed:

    • bash: ~/.local/share/bash-completion/completions/mailbox
    • zsh: ~/.local/share/zsh/site-functions/_mailbox (and the line added to .zshrc by mailbox completion install zsh)
    • fish: ~/.config/fish/completions/mailbox.fish

  5. Remove local configuration you no longer need. The default store is ~/.config/mailbox/apikey (or $XDG_CONFIG_HOME/mailbox/apikey; on Windows %USERPROFILE%\.config\mailbox\apikey). Only delete configurations and stores that are not used for other owners or environments.

Privacy and security note

The client sends a User-Agent header of the form mailbox-cli/<version> (<os>/<arch>) with every request. This allows us to count aggregated usage numbers (total requests, active client versions) on the server side. There is no "phone home" and no installation ID; no further data is sent beyond what the API call itself requires.

Treat API keys like passwords. The local store is a protected file (0600 on Unix), not an encrypted vault.