CLI

Wait for verification codes in scripts and CI with the MailBots CLI

The MailBots CLI turns waiting for a verification email into one command. It checks the inbox of a test address until a code arrives, prints only the code and exits, so a script can store it in a variable.

Install and sign in

Start the free trial or choose a plan, then create an API key in Dashboard → Developer.
Install the CLI with npm, or run it through npx without installing. It needs Node.js 18 or later.
Put the key in the MAILBOTS_API_KEY environment variable. In CI, store it as a secret.

npm install -g mailbots-cli
export MAILBOTS_API_KEY=mb_live_REPLACE_ME
mailbots domains

Wait for a code

Use a fresh address for every run, trigger the email in your app, then wait for the code. The command prints only the code, so it fits in a variable:

CODE=$(mailbots otp "signup-$RUN_ID@otp.example.com" --wait 60)

Option	Effect
`--wait 60`	Keep checking every 2 seconds for up to 60 seconds
`--since 2026-11-06T10:00:00Z`	Ignore messages received before this time
`--json`	Print the code with the message id, subject and time

The command exits with 0 when it prints a code, 2 when no code arrived in time and 1 on any other error, such as a refused API key.

Use it in GitHub Actions

- name: Read the signup code
  env:
    MAILBOTS_API_KEY: ${{ secrets.MAILBOTS_API_KEY }}
  run: |
    CODE=$(npx -y mailbots-cli otp "signup-${{ github.run_id }}@otp.example.com" --wait 90)
    echo "code=$CODE" >> "$GITHUB_OUTPUT"

Other commands

Command	What it does
`mailbots messages`	Lists recent messages; add --to with an address or --json
`mailbots domains`	Lists your hostnames and their status
`mailbots mcp`	Prints the settings that connect an AI agent to the MCP server

The CLI reads mail through the REST API and can only read. For a test written in code, the Playwright and Cypress guides call the API directly.