Skip to main content

Quickstart

This page answers one job: how to get a real inbox, receive an email, and read the OTP in under 2 minutes.

The super simple path is always the same:

  1. Create a temporary inbox.
  2. Use that inbox email address in your app.
  3. Wait for the next email.
  4. Read the extracted field you care about, like the OTP or first link.

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.

For LLMs And Agents​

If you are feeding these docs into an LLM or coding agent, use /llms.txt for the compact docs map or /llms-full.txt for the expanded version.

Node.js​

npm install postmx
import { PostMX } from "postmx";

async function main() {
  const postmx = new PostMX(process.env.POSTMX_API_KEY!);

  const inbox = await postmx.createTemporaryInbox({
    label: "signup-test",
  });

  console.log("Send your app email to:", inbox.email_address);

  const message = await postmx.waitForMessage(inbox.id, {
    timeoutMs: 30_000,
  });

  console.log("OTP:", message.otp);
  console.log("First link:", message.links[0]?.url ?? null);
}

main().catch(console.error);

Python​

pip install postmx
from postmx import PostMXSync

postmx = PostMXSync("pmx_live_...")

inbox = postmx.create_temporary_inbox({
    "label": "signup-test",
})

print("Send your app email to:", inbox["email_address"])

message = postmx.wait_for_message(
    inbox["id"],
    timeout=30.0,
)

print("OTP:", message["otp"])
print("First link:", message["links"][0]["url"] if message["links"] else None)

What Do You Want Back?​

By default, the SDK returns the full message, including extracted fields like otp, links, and intent.

If you already have a message ID and want a smaller response, content_mode is just a "what do you want back?" choice:

  • full: everything
  • otp: just message metadata plus the OTP
  • links: just message metadata plus extracted links
  • text_only: just message metadata plus plain text

Advanced​

When you need more than the super simple path: