Skip to main content

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

Method Purpose
create_inbox(local_part=, domain=, ttl_seconds=) new inbox; returns an Inbox handle
inbox.wait_for_message(match=, timeout=) first matching message, full body + extraction
inbox.wait_for_otp(match=, timeout=) best extracted OTP as a string
inbox.wait_for_link(kind=, match=, timeout=) first link, optionally verify|reset|unsubscribe
inbox.messages(since=, match=, wait=) / clear() / delete() raw listing & lifecycle
get_message(id), get_otp(id), get_links(id) direct message access
download_attachment(message_id, index) decoded attachment bytes
create_hook(label=, ttl_seconds=), list_hooks() webhook capture URL and lifecycle handles
hook.wait_for_request(match=, since=, timeout=) first matching captured request, including full headers and body
hook.requests(...), clear(), delete() / get_hook_request(id) capture listing, teardown, and direct detail access
create_domain(fqdn), verify_domain(id), list_domains(), delete_domain(id) custom domains
create_key(label=), list_keys(), revoke_key(id) API keys

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

Metadata

Release files for mailfixture 0.6.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mailfixture 0.6.2
File Size Uploaded Provenance Actions
mailfixture-0.6.2.tar.gz 20.6 kB Without provenance Details for mailfixture-0.6.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mailfixture 0.6.2
File Interpreter ABI Platform Actions
mailfixture-0.6.2-py3-none-any.whl Python 3 none any Details for mailfixture-0.6.2-py3-none-any.whl

Total release size: 35.1 kB

Release files / mailfixture-0.6.2.tar.gz

Download URL mailfixture-0.6.2.tar.gz
Size 20.6 kB
Tags Source
SHA-256 checksum
How to use checksums
9629e10a4745d072054657f606689baa8000de7103678c892bc6546eb3849ab6
BLAKE2b-256 checksum
How to use checksums
0597607600b26caa7bf3b334ca67fc2115eb17a89d1c4e8baacbc456f4554b78
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mailfixture-0.6.2-py3-none-any.whl

Download URL mailfixture-0.6.2-py3-none-any.whl
Size 14.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f2102b394e2bc513bd4dcb44f76b45bb6ae924ffeaa9141045e4ef8b0dfc48fd
BLAKE2b-256 checksum
How to use checksums
bf0633e4813ac82a31070819a05e538a0cb80fe6f33bb6a8fdc07485f7d0bbd5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mailfixture 0.6.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page