Disposable Email API: A Developer's Guide
A web inbox is great for humans, but tests and automation need a disposable email API: a way to create a throwaway address, read whatever lands in it, and tear it down — all from code. This guide walks through the building blocks and how to wire them up with MoeMail's temporary email OpenAPI.
Why an API instead of a web inbox?
Signup, email-verification, and password-reset flows are some of the hardest things to test end to end, because the verification step leaves your app and lands in an inbox. A disposable email API closes that loop: your test provisions a fresh inbox, triggers the flow, then polls the API for the verification message and extracts the link or code — deterministically, with no shared human mailbox to pollute.
Authentication with API keys
MoeMail authenticates programmatic requests with an API key sent in the X-API-Key header. Generate a key from your profile after signing in, then attach it to every request. Keys are scoped to the email and config endpoints and are subject to your account's monthly quota, so treat them like secrets and rotate them if leaked.
The core operations
- Create a mailbox — request a new random or custom address with a chosen expiry.
- List messages — poll the mailbox for newly received emails.
- Read a message — fetch a single message's headers, text, and HTML body.
- Let it expire — do nothing; the mailbox and its messages are cleaned up automatically.
A minimal polling call looks like sending your key as a header to the emails endpoint, for example: curl -H "X-API-Key: YOUR_KEY" https://moemail.app/api/emails. The exact request and response shapes are documented in the OpenAPI definition.
Webhooks: stop polling
Polling works, but it adds latency and wastes requests. MoeMail can fire a webhook the moment a message arrives, so your test or backend reacts instantly instead of looping. Point the webhook at an endpoint your test harness controls, verify the payload, and resolve the waiting step as soon as the message lands. Keep handlers fast — respond within a few seconds, because slow or non-2xx responses trigger retries.
Rate limits and quotas
API usage counts against your account's monthly OpenAPI quota. For large test suites, reuse a mailbox across assertions where you can, batch your polls, and prefer webhooks over tight polling loops. If you need more headroom, higher roles and shop quotas raise the limits — or run your own instance (see self-hosted vs hosted temporary email).
Putting it together in tests
Whether you use Playwright, Cypress, or Selenium, the pattern is the same: wrap the create/poll/read calls in a small helper (a fixture or custom command), provision an inbox at the start of the test, drive your UI to the verification step, then await the message through the helper. Because every run gets its own address, tests stay isolated and parallel-safe.
Next steps
Read the full API docs, grab a key from your profile, and try a single create-and-poll round trip. Then automate it end to end: see how to automate email-verification testing and receiving inbound email via webhooks. New to the concept? Start with what is temporary email, or just create a mailbox in the dashboard to see what the API returns.