# PostMX Docs for LLMs and Coding Agents

This file is generated from the docs source and reflects the current public docs structure.

Canonical docs:
- https://docs.postmx.co/
- https://docs.postmx.co/quickstart

What PostMX docs cover best:
- Create a real inbox for a test or workflow
- Receive real emails
- Extract structured fields like OTPs and links
- Poll for a message or consume push webhooks

Default product mental model:
1. Create a temporary inbox.
2. Use the inbox email address in the app or test.
3. Wait for the next email.
4. Read extracted fields like otp or first link.

Critical semantics to preserve:
- waitForMessage() and wait_for_message() return the latest existing message immediately if the inbox already has one; otherwise they wait for the next incoming email until the timeout.
- The beginner path should prefer "temporary inbox", "wait for next email", and "extract OTP or first link" language over infrastructure-heavy wording.
- content_mode should be explained as a simple "what do you want back?" choice.
- Advanced controls like lifecycle_mode, ttl_minutes, wildcard addresses, retries, webhooks, and routing should come after the beginner path.

Generated docs map:
- /
  PostMX Docs
  PostMX SDK and CLI documentation for creating a temporary inbox, waiting for the next email, reading extracted fields, and verifying webhooks.
  Main sections: The Super Simple Path; Pick Your SDK; What Do You Want Back?; Official Example Repos; Advanced
- /quickstart
  Quickstart
  Get a real PostMX inbox, wait for the next email, and read the OTP or first link in under 2 minutes.
  Main sections: For LLMs And Agents; Node.js; Python; What Do You Want Back?; Advanced
- /sdks/node
  Node.js SDK
  Official PostMX Node.js and TypeScript SDK docs for creating a temporary inbox, waiting for the next email, and reading extracted fields like OTPs and links.
  Main sections: Install; Super Simple Path; What Do You Want Back?; Create the client; Advanced; Error handling
- /sdks/python
  Python SDK
  Official PostMX Python SDK docs for creating a temporary inbox, waiting for the next email, and reading extracted fields like OTPs and links.
  Main sections: Install; Super Simple Path; What Do You Want Back?; Create the client; Advanced; Error handling
- /cli/overview
  CLI
  Official PostMX CLI reference with quickstart commands for inbox creation, waiting for messages, OTP extraction, message inspection, and webhook setup.
  Main sections: Install; Authenticate; Quickstart; Output modes; Interactive mode; Command reference
- /guides/example-apps
  Example Apps
  Official runnable PostMX example apps for Node.js and Python, with links to the source repos and the matching SDK docs.
  Main sections: Node.js and TypeScript; Python; Which one should you choose?
- /guides/test-otp-flows
  Test OTP Flows
  End-to-end PostMX examples for testing signup, login, and verification-code flows with the Node.js SDK, Python SDK, and CLI.
  Main sections: Node.js example; Python example; CLI example; Tips
- /guides/verify-webhooks
  Verify Webhooks
  Create and verify PostMX webhooks with signing secrets, raw request bodies, and signature checks in Node.js and Python.
  Main sections: Create the webhook; What PostMX sends to your server; Node.js verification; Python verification; Signature model; Minimal verification example
- /api
  REST API Reference
  Interactive PostMX REST API reference with OpenAPI schema, authentication notes, and webhook endpoint details.
  Main sections: Quick facts
- /api/rest
  REST API
  PostMX REST API overview, authentication notes, and links to the interactive OpenAPI reference and raw spec.
  Main sections: Open the reference; Authentication; Base URL; What the API covers; Webhook payloads; Good next steps

Node.js quickstart pattern:
- Create a PostMX client
- Call createTemporaryInbox({ label })
- Use inbox.email_address in the app or test
- Call waitForMessage(inbox.id, { timeoutMs })
- Read message.otp or message.links[0]?.url

Python quickstart pattern:
- Create a PostMXSync or async PostMX client
- Call create_temporary_inbox({"label": ...})
- Use inbox["email_address"] in the app or test
- Call wait_for_message(inbox["id"], timeout=...)
- Read message["otp"] or the first extracted link

REST API basics:
- Base URL: https://api.postmx.co
- Auth header: Authorization: Bearer pmx_live_...
- Main endpoints:
  - GET /v1/inboxes
  - POST /v1/inboxes
  - GET /v1/inboxes/{inbox_id}/messages
  - GET /v1/messages
  - GET /v1/messages/{message_id}
  - POST /v1/webhooks