Skip to main content

mailpier-inbox

Python client for MailPier Inbox: give each test its own email address, wait for the mail your app sends, and read its one-time code and links. Python 3.9+, typed, one dependency (requests). Includes a pytest fixture and a fake MailPier API for offline tests.

Quick start

from mailpier_inbox import MailPierInbox
inbox = MailPierInbox()                                   # key from MAILPIER_API_KEY
address = inbox.new_address(prefix="signup")              # signup-k3v9q2mz7a@qa.acme.mailpier.io
sign_up(address)                                          # your app sends the mail
mail = inbox.wait_for_message(address, subject_contains="Confirm", timeout=60)
print(mail.code, mail.first_link("verify"))               # 482913 https://app.example.com/verify?t=...

Create the API key on your environment's API keys page and keep it in a secret (MAILPIER_API_KEY).

pytest

Installing the package registers the plugin. The mailpier_inbox fixture returns the next mail to an address on each wait:

def test_sign_up(mailpier_inbox, page):
    email = mailpier_inbox.new_address()
    page.fill("#email", email); page.click("text=Create account")
    page.fill("#code", mailpier_inbox.wait_for_code(email))
    # or: page.goto(mailpier_inbox.wait_for_link(email, "verify"))

@pytest.mark.mailpier_cleanup (or pytest --mailpier-cleanup) deletes the test's mail afterwards. Without MAILPIER_API_KEY the fixture fails with a clear message. For offline tests also request mailpier_fake: the fixture then talks to an in-memory fake API and you "send" mail with mailpier_fake.deliver(email, subject=..., text=..., html=...) (see examples/).

API

Call What it does
MailPierInbox(api_key=None, base_url=None, *, max_retries=5, max_retry_delay=60.0, session=None) Key from MAILPIER_API_KEY, root from MAILPIER_BASE_URL or https://api.mailpier.io. Context manager.
new_address(prefix=None, domain=None) A fresh random address of the key's environment.
wait_for_message(to, *, subject_contains=None, timeout=60, since=None, after_id=None) The oldest match received at or after since; long-polls; raises MailPierTimeoutError (a TimeoutError).
wait_for_next_message(previous, to, ...) The mail after previous (never previous again).
list_messages(to=None, *, subject_contains=None, since=None, take=50, skip=0) Newest first, at most 100 per call.
get_message(id) / get_raw(id) / get_attachment(id, index) Full mail / .eml bytes / attachment bytes; None when gone.
delete_message(id) / delete_all(to) Clean up.
message.code / message.first_link(contains=None) The first one-time code; the first link whose URL or text contains it.

Errors raise MailPierInboxError with status (0 = unreachable) and the server's message. 429 is retried after Retry-After, 502/503/504 and connection errors with backoff, up to max_retries times.

Offline: the fake API

from mailpier_inbox.testing import FakeMailPier
with FakeMailPier() as fake:                              # 127.0.0.1, key "mpi_test_key", zone qa.demo.mailpier.io
    inbox = MailPierInbox(api_key=fake.api_key, base_url=fake.url)
    fake.deliver(address, subject="Confirm", text="Your code is 482913")

Develop

python -m venv .venv, .venv\Scripts\pip install -e .[test], .venv\Scripts\python -m pytest; runnable example: python examples/quickstart.py. ..\test-all.ps1 runs everything. License: MIT.

Metadata

Release files for mailpier-inbox 0.1.0

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

Source distribution (sdist)

Source distribution for mailpier-inbox 0.1.0
File Size Uploaded Provenance Actions
mailpier_inbox-0.1.0.tar.gz 21.5 kB Without provenance Details for mailpier_inbox-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mailpier-inbox 0.1.0
File Interpreter ABI Platform Actions
mailpier_inbox-0.1.0-py3-none-any.whl Python 3 none any Details for mailpier_inbox-0.1.0-py3-none-any.whl

Total release size: 40.9 kB

Release files / mailpier_inbox-0.1.0.tar.gz

Download URL mailpier_inbox-0.1.0.tar.gz
Size 21.5 kB
Tags Source
SHA-256 checksum
How to use checksums
2345bcb1cf05041a044e73e9e2d4037eaeb81f56b0b4d8c594c35fd152d438ee
BLAKE2b-256 checksum
How to use checksums
da8a927bcf941b7a8f2267acebcb179a8570279f220ecc12168ce5b89617c7a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / mailpier_inbox-0.1.0-py3-none-any.whl

Download URL mailpier_inbox-0.1.0-py3-none-any.whl
Size 19.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
474b1c2a390691620bccd8a847eb814ab0790b96524f43dd1be40f05f753e006
BLAKE2b-256 checksum
How to use checksums
364ad01c9eaf7be053eb073f69799f7d3d110468e7b5d2d45da63b8fc842971b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for mailpier-inbox 0.1.0

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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

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