How to Test OTP Flows with MailGX API

Create an inbox via API, trigger your signup flow, capture the OTP — all in one automated test.

Automate OTP and email verification testing with the MailGX REST API — from manual curl tests to full CI pipeline integration.

Why automate OTP testing?

One-time passcodes and email verification links are high-risk failure points in any auth flow. Manual testing with personal inboxes is slow, non-repeatable, and impossible to run on every deploy.

The MailGX API lets you programmatically create disposable inboxes, trigger your application's email flow, poll for incoming messages, extract OTP patterns, and assert verification success — all without SMTP infrastructure.

Manual OTP test workflow

Before automating, validate the flow manually to confirm deliverability.

  • Create a MailGX account and generate an API key from the dashboard
  • Call POST /api/v1/mailboxes to create a test inbox
  • Paste the returned address into your app's signup or MFA enrollment form
  • Submit the form to trigger the OTP email
  • Call GET /api/v1/messages?address=... to poll for the verification message
  • Parse the OTP code or activation link from the message body
  • Submit the code and confirm session or redirect state

Automating OTP tests in CI/CD

Wrap MailGX API calls in your test framework. A typical GitHub Actions job creates a mailbox, runs Playwright or Cypress to fill the signup form, polls the messages endpoint with a retry loop, regex-extracts the six-digit code, and submits it programmatically.

Use realistic wait intervals — most OTP emails arrive within seconds but allow 15–30 second timeouts in CI. Run parallel jobs with separate mailboxes to avoid cross-test contamination.

OTP testing best practices

Use premium private domains when staging environments block public disposable hostnames. Delete test mailboxes after each run to stay within rate limits. Log message IDs for debugging failed assertions.

Test both HTML and plain-text OTP templates. Verify link-based activation flows separately from numeric code flows. See full endpoint schemas and curl examples at API documentation.

Frequently asked questions

How do I extract OTP codes from MailGX messages?

Poll GET /api/v1/messages and apply a regex like /\b\d{4,8}\b/ to the message body in your test script.

How fast do OTP emails arrive via the API?

Most verification messages appear within seconds. Use retry loops with 2–5 second intervals in automated tests.

Where is the MailGX API documentation?

Full endpoint reference with examples is at API documentation.