{receiver}

CLI

receiver creates inboxes, waits for email and prints codes and links from your shell, with JSON output and exit codes made for scripts and agents.

Install

bash
npm install -g @receiverdotemail/cli

Or run it without installing:

bash
npx @receiverdotemail/cli whoami

Authentication

The CLI uses RECEIVER_API_KEY when it is set. Otherwise it reads the key that receiver login saved to ~/.config/receiver/config.json. Either way the key decides the project, so no command needs a project id.

bash
# In CI or an agent's environment
export RECEIVER_API_KEY=recv_live_your_key

# On your machine
receiver login

Commands

receiver login: Save an API Key

Checks the key with /whoami and stores it. Without --key it prompts for one (when run in a terminal).

bash
receiver login --key recv_live_your_key

receiver whoami: Show the Project

bash
$ receiver whoami
Project:      Signup tests
Project ID:   proj_abc123
Email suffix: [email protected]
API key:      CI (key_abc123)

receiver inbox new: Mint an Address

Prints a new address. With --json it also prints since, the time to wait from.

bash
$ receiver inbox new --prefix signup
[email protected]

$ receiver inbox new --prefix signup --json
{"address":"[email protected]","since":"2026-11-05T10:00:00.000Z"}

receiver wait: Wait for an Email

Waits for mail to an address and prints its subject, sender and a summary of the body. --otp prints only the code; --links prints one link per line.

bash
receiver wait <address> [--since ISO] [--timeout seconds] [--otp | --links]

$ receiver wait [email protected] --links
https://acme.example/verify?token=...
https://acme.example/help

Without --since it looks back 60 seconds. Pass the since from inbox new --json, or the receivedAt of the last email, to be exact (see Concepts).

receiver otp: Print the Code

Shorthand for wait --otp. Prints the code and nothing else, so it pipes cleanly.

bash
$ CODE=$(receiver otp [email protected] --timeout 60)
$ echo $CODE
847291

receiver list: Recent Emails

bash
$ receiver list --address [email protected] --limit 5
RECEIVED              FROM                TO                                      SUBJECT          ID
2026-11-05T10:00:04Z  [email protected]  [email protected]  Your Acme code   email_xyz
2026-11-05T09:58:41Z  [email protected]  [email protected]  Welcome to Acme  email_uvw

receiver read: Print a Body

Prints the text body. --html prints the HTML body; --raw prints the raw RFC 822 message.

bash
receiver read email_xyz --html > email.html

receiver watch: Stream New Mail

Prints each new email as it arrives, for the whole project or one address, until you press Ctrl-C. With --json it prints one JSON object per line.

bash
receiver watch [email protected]

receiver test-email: Send Yourself a Test

Sends "Your Receiver.email test code: 123456" to one of your project's addresses, to check the whole path end to end. Limited to 10 per project per hour.

bash
ADDRESS=$(receiver inbox new)
receiver test-email "$ADDRESS"
receiver otp "$ADDRESS"

Global Flags

  • --json: machine output, one JSON document per command (one per line for watch). Diagnostics still go to stderr.
  • --api-url: another API base URL, for example a staging environment. RECEIVER_API_URL does the same.

Exit Codes

CodeMeaning
0Success
1Error: bad key, bad input, network or API error (message on stderr)
2Timeout: nothing arrived before --timeout

Human output goes to stdout and diagnostics to stderr, so a script can branch on the code:

bash
if CODE=$(receiver otp "$ADDRESS" --timeout 90); then
  ./verify.sh "$CODE"
elif [ $? -eq 2 ]; then
  echo "No code within 90 s" >&2
  exit 1
fi

Next Steps