Metadata-Version: 2.4
Name: mailpier-inbox
Version: 0.1.0
Summary: MailPier Inbox client for Python tests: a fresh email address per test, wait for the mail, read its code and links. Includes a pytest fixture.
Author: Solutions Group Unlimited
License-Expression: MIT
Project-URL: Homepage, https://mailpier.io
Project-URL: Documentation, https://mailpier.io/docs
Keywords: email,testing,inbox,otp,pytest,e2e,mailpier
Classifier: Framework :: Pytest
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# mailpier-inbox

Python client for [MailPier Inbox](https://mailpier.io): 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

```python
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:

```python
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

```python
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.
