Menu Python

SDKs

Python SDK

The official client of the fake-email.pro API for Python, in a sync and an asyncio flavour. It covers every endpoint with typed models, turns errors into exceptions you can catch by type, retries rate limits on its own, and waits for the email of an end-to-end test – handing back its one-time code or confirmation link. Open source under the MIT license.

Python 3.9+, sync and async clients on httpx, fully typed

Terminal
pip install fake-email-pro

fake-email-pro on PyPISource on GitHub

API key

Create a key as in Quickstart and put it in the FAKE_EMAIL_API_KEY environment variable – a CI secret on a build agent. The client reads it from there, or takes it as the first argument. The API is server-to-server, without CORS: call it from the test process, never from the page under test.

Quickstart

Python
from fake_email_pro import FakeEmail

with FakeEmail() as client:  # reads FAKE_EMAIL_API_KEY
    mailbox = client.mailboxes.create()
    print("Sign up with", mailbox.address)

    try:
        # Long-polls the mailbox for up to 60 s and returns the one-time code
        code = client.wait_for_code(mailbox.address, subject="verification")
        print(code)
    finally:
        client.mailboxes.delete(mailbox.address)

pytest and Playwright

One client for the session, a fresh mailbox for every test, and wait_for_link waiting across as many long polls as the timeout allows.

Python
import pytest
from fake_email_pro import FakeEmail


@pytest.fixture(scope="session")
def fake_email():
    with FakeEmail() as client:
        yield client


@pytest.fixture
def mailbox(fake_email):
    # A fresh mailbox for every test, deleted when the test ends
    mailbox = fake_email.mailboxes.create()
    yield mailbox
    fake_email.mailboxes.delete(mailbox.address)


def test_sign_up_link(page, fake_email, mailbox):  # page: pytest-playwright
    page.goto("/sign-up")
    page.get_by_label("Email").fill(mailbox.address)
    page.get_by_role("button", name="Sign up").click()

    link = fake_email.wait_for_link(mailbox.address, subject="Confirm")
    page.goto(link)

asyncio

AsyncFakeEmail has the same methods, awaited; it runs on asyncio and trio.

Python
import asyncio

from fake_email_pro import AsyncFakeEmail


async def main():
    async with AsyncFakeEmail() as client:
        mailbox = await client.mailboxes.create()
        try:
            message = await client.wait_for_message(mailbox.address, from_="acme.example")
            print(message.subject, message.code, message.confirm_link)
        finally:
            await client.mailboxes.delete(mailbox.address)


asyncio.run(main())

Waiting for an email

  • wait_for_message(address, ...) – the first message that matches from_, subject and an optional match function. It repeats the 60-second long poll until timeout (60 s by default), then raises WaitTimeoutError.
  • wait_for_code and wait_for_link – the same, returning the code or the confirmation link the API read out of the email; a message without one is skipped.
  • For the next email in the same mailbox, pass after with the id of the one you have. More on the flow in Email testing.
Python
first = client.wait_for_message(address, subject="Welcome")

# Strictly after the first one: nothing that arrived in between is lost
second = client.wait_for_message(
    address,
    after=first.id,
    match=lambda message: message.attachments_count > 0,
)

Methods and models

Options after the path arguments are keyword-only. iter walks every page; models are frozen dataclasses with snake_case fields and timezone-aware datetimes.

The client has a method for each endpoint of the API; their parameters and responses are in Endpoints.

Errors and retries

Every error of the API is thrown as an APIError with the HTTP status, the error code, the message and the rate-limit headers; its subclass names the case: BadRequestError 400, AuthenticationError 401, QuotaExhaustedError 402, PermissionDeniedError 403, NotFoundError 404, ConflictError 409, RateLimitError 429, InternalServerError 5xx. What each status and code means is in Errors. A request that got no response throws APIConnectionError, and one whose HTTP attempt outlasted its timeout APITimeoutError, a subclass of it.

Retries (twice by default) wait the Retry-After of the response, or a short backoff without one. A 429 and a 503 are retried on every method, since the server refused them before doing anything – except a 503 that asks to come back in more than 5 s, which is thrown at once. A network error, a timed-out attempt, a 502, a 504 and Cloudflare's 520–524 are retried on GET and DELETE only, so a mailbox is never created twice; a retried DELETE that gets 404 counts as done, since the attempt before it went through. A wait helper waits out 429, 502–504, 520–524 and connection errors until its own deadline, and then throws WaitTimeoutError.

Configuration

Python
import httpx
from fake_email_pro import FakeEmail

client = FakeEmail(
    api_key="fep_...",  # default: FAKE_EMAIL_API_KEY
    base_url="https://api.fake-email.pro",  # default
    timeout=30.0,  # seconds per request; a wait request always gets its server timeout + 10 s
    max_retries=2,  # 0 disables retries
    user_agent="my-e2e-suite/1.4",  # prepended to fake-email-pro-python/<version>
    # proxies, transports, hooks; proxy= needs httpx 0.26+ (proxies= before it)
    http_client=httpx.Client(proxy="http://proxy.internal:3128"),
)

AsyncFakeEmail takes the same arguments, with an httpx.AsyncClient. Use either client as a context manager, or call close(); a client you pass in is yours to close.

Other languages

C# / .NET, Go, Java, JavaScript / TypeScript, PHP – or every SDK and the OpenAPI document for any other language.

Something missing, confusing or wrong on this page? Tell us