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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.