Receiving Inbound Email via Webhooks

Polling an inbox works, but it adds latency and wastes requests. Webhooks flip the model: instead of asking "any mail yet?" in a loop, the service calls you the moment a message lands. This guide covers how inbound-email webhooks work with MoeMail's API and how to handle them reliably.

Polling vs webhooks

Polling repeatedly hits the messages endpoint until something shows up — simple, but slow and quota-hungry. A webhook is a URL you own that the provider POSTs to when an event happens (here: a new inbound email). Your endpoint reacts instantly, with no loop.

How it works

1. Register a webhook URL that you control (a backend route, or an endpoint your test harness exposes).
2. When mail arrives at your temporary mailbox, MoeMail POSTs the message payload to that URL.
3. Your handler verifies the request, parses the email, and acts — store it, resolve a waiting test step, or trigger downstream logic.

Respond fast — or get retried

Webhook handlers must reply quickly (within a few seconds) with a 2xx status. Any non-2xx — or a slow handler — is treated as a failure and retried, so a sluggish handler can receive the same event multiple times. Two rules follow: keep the handler lightweight (don't do heavy DB work inline — enqueue it), and make processing idempotent so duplicate deliveries are harmless.

Verify the payload

Your webhook URL is effectively public, so confirm requests really come from MoeMail before trusting them. Validate any signing/shared-secret your account configures, ignore unexpected shapes, and never act on unverified input.

Webhooks in tests

For automated email-verification testing, a webhook removes polling entirely: your test waits on a promise that resolves when the webhook fires, then extracts the link or code. That's faster and far less flaky than a poll loop.

Get started

See the OpenAPI docs for the webhook payload format, point a URL at your handler, and create a mailbox to send yourself a test message.