Skip to main content

REST API

PostMX exposes a public REST API for creating inboxes, listing messages, fetching full or reduced message detail, and registering webhook targets for email.received and email.enriched events.

Open the reference​

Authentication​

Use a bearer token issued from the PostMX dashboard:

Authorization: Bearer pmx_live_...

Base URL​

https://api.postmx.co

What the API covers​

  • GET /v1/inboxes
  • POST /v1/inboxes
  • GET /v1/inboxes/{inbox_id}/messages
  • GET /v1/messages
  • GET /v1/messages/{message_id}
  • POST /v1/webhooks

Webhook payloads​

When PostMX delivers a webhook, it sends a signed JSON POST request containing:

  • event metadata: id, type, created_at
  • data.inbox: inbox metadata
  • data.message: the full message payload, including deterministic extraction fields such as otp, links, and intent, plus the additive analysis object for asynchronous message analysis

Message detail responses also include the additive analysis object:

  • analysis.status: none, queued, complete, failed, or skipped_quota
  • analysis.detected_otp: model-derived OTP candidate, separate from the deterministic top-level otp
  • analysis.sender_name, analysis.category, analysis.extracted_id, analysis.amount_mentioned
  • analysis.is_urgent, analysis.action_required, analysis.summary

Inbox create/list responses now also expose message_analysis settings so you can control where background analysis runs:

  • all
  • disabled
  • allowlist
  • blocklist

For the full delivery model, headers, signature flow, and processing guidance, read Verify Webhooks.

Good next steps​

  • Read the Node.js SDK if you want typed application code.
  • Read the Python SDK if you want async or sync Python integration.
  • Read the CLI docs if you want to work from a terminal or CI pipeline.