Getting started

Getting Started with PostMX: The Developer’s Guide to Painless Email Testing

Sending emails is easy. Proving that the right code or link reached the right inbox in CI is the part that usually hurts. PostMX keeps that flow short: create a temporary inbox, trigger the email, wait for the message, and read the OTP or link directly.

SDK guide CLI 7 min read April 2026

Start free Browse articles

Start with a temporary inbox and keep the rest of the workflow programmable.

Core concept

Ephemeral inboxes keep tests isolated

The common mistake in email testing is reusing the same inbox for every run. Once parallel jobs start sharing a mailbox, messages collide, stale mail lingers, and the next assertion becomes a guess. PostMX avoids that by giving each run a fresh inbox that you can destroy when the test is done.

Why this matters in CI

CI does not care how clever the mailbox setup is. It only cares that the right email arrived, that the OTP or link was extracted, and that the test finished without waiting on a human inbox.

Minimal Node flow

import { PostMX } from "postmx";

const postmx = new PostMX(process.env.POSTMX_API_KEY!);

async function main() {
  const inbox = await postmx.createTemporaryInbox({ label: "signup-test" });
  console.log("Send your app email to:", inbox.email_address);

  const email = await postmx.waitForMessage(inbox.id);
  console.log("OTP:", email.otp);
}

main().catch(console.error);

Local debugging

Use the CLI when you want eyes on the raw message

Automated tests are the main story, but local development benefits from a quick console view of what just arrived. The PostMX CLI lets you inspect messages without leaving the terminal.

CLI commands

npm install -g postmx-cli

postmx -i
postmx inbox list-msg inb_123abc

Takeaway

Start with one inbox, one message, and one assertion

PostMX is designed to keep the path from email send to test assertion as short as possible. That means fewer mocks, fewer moving parts, and more confidence that the flow you checked locally will behave the same way in CI.

OTP Real inbox

Use the message payload

Read the OTP or link from the message returned by PostMX instead of scraping the UI.

CI Isolation

Keep runs separate

Temporary inboxes keep parallel jobs from fighting over the same mailbox.

Debugging CLI

Inspect when you need to

Use the CLI for a fast look at incoming mail during local development.

Ready to try it?

Ship email tests without turning the inbox into the problem

Create the inbox, wait for the message, and keep the verification logic in code where it belongs.

Start free Read docs