Skip to main content

PostMX CLI

The PostMX CLI 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​

npm install -g postmx-cli

You can also run it without a global install:

npx postmx-cli --help

Authenticate​

export POSTMX_API_KEY=pmx_live_...

You can also pass the key explicitly:

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

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, 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).
  • Live watch mode that polls every 2 seconds and prints new message summaries as they appear.

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.
  • 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 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 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.