mailfixture

Email fixtures for your test suite. Create a programmatic inbox in one call, point your app's signup / OTP / password-reset flow at it, then wait for the email — parsed, with the OTP and links already extracted.

Receive-only, built for CI: long-polling instead of retry loops, zero dependencies outside the Python standard library, Python 3.9+.

pip install mailfixture

Quickstart

Create a key in Dashboard → API keys and export it as MAILFIXTURE_API_KEY.

from mailfixture import MailFixture

mfx = MailFixture()  # reads MAILFIXTURE_API_KEY

def test_signup_sends_otp(page):
    inbox = mfx.create_inbox(ttl_seconds=900)

    page.goto("/signup")
    page.fill("#email", inbox.email_address)
    page.click("text=Send code")

    otp = inbox.wait_for_otp(timeout=30)   # long-polls; no sleep()
    page.fill("#otp", otp)

Waiting for a magic link instead:

link = inbox.wait_for_link(kind="verify", timeout=30)
page.goto(link.url)

Capturing a webhook your app sends:

hook = mfx.create_hook(label="checkout", ttl_seconds=900)
configure_app_webhook(hook.ingest_url)  # your test setup
trigger_checkout()
request = hook.wait_for_request(match="body:order.created")
assert request.method == "POST"
hook.delete()

Everything on the wait helpers is server-side long-polling: the request is held open until a matching message arrives (or the timeout passes, raising mailfixture.MailFixtureTimeout).

API surface

match filters with subject:, from:, or to: prefixes; a bare term matches the subject.

Capture-hook matching accepts method:, path:, and body:; a bare term matches the first 32 KiB of request body bytes. Returned detail bodies are complete.

Errors are raised as mailfixture.MailFixtureError carrying the API's RFC 7807 status / title / detail fields.

Development

PYTHONPATH=src python3 -m unittest discover -s tests

Docs: https://mailfixture.com/docs