Skip to main content

PostMX CLI Beta

The PostMX CLI beta is a good fit when you want to work from a terminal, wire PostMX into shell scripts, or inspect inboxes quickly during development.

The package name is postmx-cli. The executable is postmx.

Install​

Install with Homebrew:

brew tap postmx/tap
brew install postmx

Or install with npm:

npm install -g postmx-cli

You can also run it without a global install:

npx postmx-cli --help

brew install postmx without tapping is not available until the formula is accepted into homebrew-core.

Authenticate​

export POSTMX_API_KEY=pmx_live_...

You can also pass the key explicitly:

postmx inbox create --api-key pmx_live_... --label signup-test

Or save it once for future CLI use:

postmx auth login --api-key pmx_live_...

When available, the CLI stores credentials in your OS secure keychain and keeps only metadata in the config file. If a secure store is unavailable, it falls back to ~/.config/postmx/config.json or $XDG_CONFIG_HOME/postmx/config.json.

Lookup order is:

  1. --api-key
  2. POSTMX_API_KEY
  3. Saved CLI config at ~/.config/postmx/config.json or $XDG_CONFIG_HOME/postmx/config.json

Quickstart​

Create a temporary inbox:

postmx inbox create --label signup-test --lifecycle temporary --ttl 15

Wait until the inbox has a message:

postmx inbox wait inb_abc123 --timeout 30

Fetch only the OTP from a message:

postmx message get msg_abc123 --content-mode otp

Create a webhook:

postmx webhook create \
  --label app-events \
  --target-url https://example.com/webhooks/postmx

Use a final public HTTPS endpoint. The API rejects localhost targets, embedded credentials, and private or reserved IP literals.

Output modes​

  • When you run the CLI in a terminal, it prints human-friendly output.
  • When output is piped, it automatically switches to JSON.
  • You can force JSON with --json.

Example:

postmx inbox create --label signup-test --lifecycle temporary --ttl 15 --json

Interactive mode​

Launch the terminal UI:

postmx -i

If you run postmx with no command in a real terminal, it also opens interactive mode automatically.

What interactive mode currently includes:

  • Main menu with Inboxes, Find Emails By Address, Create inbox, and Webhooks.
  • Inbox browser that shows up to 50 inboxes and includes a wildcard row when your account has a wildcard address.
  • Per-inbox actions for Messages, Details, and Watch (live poll).
  • Recipient lookup that opens an account-wide message feed for one exact to_email address.
  • Message feeds with inline refresh and direct detail navigation.
  • Live watch mode that polls every 2 seconds, keeps new messages selectable, and lets you open full details without leaving the poller.
  • Inbox creation now jumps directly into the live watch screen so you can wait for incoming mail right away.

Current limitation:

  • Webhooks is present in the menu, but webhook browsing is not implemented yet. Use postmx webhook create from the command line for now.

Key controls:

  • ↑ and ↓ to move.
  • Enter to open.
  • r to refresh message feeds manually.
  • Space to pause or resume live polling while you are on the watch screen.
  • Esc to go back.
  • q to quit.

Command reference​

postmx inbox create​

Create an inbox.

postmx inbox create --label ci-test --lifecycle temporary --ttl 15

Flags:

  • --label: Required.
  • --lifecycle: Optional. Defaults to temporary.
  • --ttl: Optional TTL in minutes. Current API limits for temporary inboxes are 10 to 60.
  • --api-key: Optional override instead of POSTMX_API_KEY.
  • --base-url: Optional API base URL override.
  • --json: Force JSON output.

postmx auth login​

Save an API key locally for future CLI use.

postmx auth login --api-key pmx_live_...

postmx auth logout​

Remove the locally saved API key.

postmx auth logout

postmx inbox list-msg <inbox_id>​

List messages in an inbox.

postmx inbox list-msg inb_abc123 --limit 20

Flags:

  • --limit
  • --cursor
  • --api-key
  • --base-url
  • --json

postmx inbox wait <inbox_id>​

Poll an inbox until a message arrives.

postmx inbox wait inb_abc123 --timeout 30 --interval 1

Flags:

  • --timeout: Seconds to wait before failing. Default 60.
  • --interval: Seconds between polls. Default 1.
  • --api-key
  • --base-url
  • --json

inbox wait returns the latest message once the inbox is non-empty.

postmx messages list​

List messages for one exact recipient email across the authenticated account.

postmx messages list --recipient-email [email protected] --limit 20

Flags:

  • --recipient-email: Required exact recipient email address.
  • --limit
  • --cursor
  • --api-key
  • --base-url
  • --json

postmx message get <message_id>​

Fetch a message by ID.

postmx message get msg_abc123
postmx message get msg_abc123 --content-mode otp
postmx message get msg_abc123 --content-mode links
postmx message get msg_abc123 --content-mode text_only

Flags:

  • --content-mode: full, otp, links, or text_only.
  • --api-key
  • --base-url
  • --json

postmx webhook create​

Create a webhook target for email.received.

postmx webhook create \
  --label signup-events \
  --target-url https://example.com/webhooks/postmx \
  --inbox-id inb_abc123

Flags:

  • --label: Required.
  • --target-url: Required. Use a public HTTPS endpoint.
  • --inbox-id: Optional. Scope the webhook to one inbox.
  • --api-key
  • --base-url
  • --json

Good CLI patterns​

  • Use --json in CI so downstream steps get stable machine-readable output.
  • Use inbox wait for simple test automation when you do not need a full SDK.
  • Use message get --content-mode otp when you only care about the code.
  • Use interactive mode when you want a quick visual inbox browser during debugging.