Test OTP Flows

This is the fastest real-world PostMX workflow:

1. Create a temporary inbox.
2. Trigger your product to send an email.
3. Wait for the next email.
4. Read the OTP or verification 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.

If you want runnable starter projects for this flow, see Example Apps.

Node.js example

import { PostMX } from "postmx";

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

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

  console.log("Use this test email:", inbox.email_address);

  // Trigger your app to send a login code to inbox.email_address here.

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

  console.log("OTP:", message.otp);
}

run().catch(console.error);

Python example

from postmx import PostMXSync

postmx = PostMXSync("pmx_live_...")

inbox = postmx.create_temporary_inbox({
    "label": "login-otp",
})

print("Use this test email:", inbox["email_address"])

# Trigger your app to send a login code to inbox["email_address"] here.

message = postmx.wait_for_message(inbox["id"], timeout=30.0, interval=1.0)
print("OTP:", message["otp"])

CLI example

Create the inbox:

postmx inbox create --label login-otp --lifecycle temporary --ttl 15 --json

Use the returned email_address in your app, then wait for the message:

postmx inbox wait inb_abc123 --timeout 30 --json

Fetch only the OTP if you already know the message ID:

postmx message get msg_abc123 --content-mode otp

Tips

• Use temporary inboxes for one test run, one suite, or one CI job.
• Keep TTL short so old test data expires automatically.
• Prefer waitForMessage() or wait_for_message() over hand-written polling loops unless you need custom logic.
• Think of content_mode as "what do you want back?" and use otp when your tests only care about the verification code.