Skip to main content

fake-email-pro

PyPI Python versions CI License: MIT

The official Python client for the fake-email.pro API: disposable mailboxes over HTTP for testing signup, OTP and magic-link emails in pytest, Playwright and CI.

Create a real inbox in one call, let your app send to it, and get the one-time code or the confirmation link back — no mail server, no shared test inbox, no regex over HTML.

from fake_email_pro import FakeEmail

client = FakeEmail()  # reads FAKE_EMAIL_API_KEY
mailbox = client.mailboxes.create()

# ... your app sends a verification email to mailbox.address ...

code = client.wait_for_code(mailbox.address)  # "048213"
  • Sync and async clients with the same API, fully typed (py.typed), Python 3.9+.
  • Test helpers that long-poll the server: wait_for_message, wait_for_code, wait_for_link.
  • One-time codes and confirm links are extracted by the server, so you don't parse emails yourself.
  • Automatic retries on rate limits and transient errors, honoring Retry-After.
  • One small dependency: httpx.

Links: Product page · SDK docs · API reference · Changelog

Install

pip install fake-email-pro

or uv add fake-email-pro, or poetry add fake-email-pro.

Get an API key

API access comes with every account, the free plan included:

  1. Sign in at fake-email.pro.
  2. Open Settings → API keys (fake-email.pro/settings/api-keys) and create a key. It starts with fep_ and is shown only once.
  3. Put it in the FAKE_EMAIL_API_KEY environment variable (or a CI secret of that name).
export FAKE_EMAIL_API_KEY=fep_...

Need a bigger monthly mailbox quota or higher rate limits? See the PRO plan. Your current numbers are always in client.limits.get().

The API is server-to-server: never ship the key to browser JavaScript.

Quickstart

from fake_email_pro import FakeEmail

with FakeEmail() as client:
    mailbox = client.mailboxes.create()
    print(mailbox.address)  # e.g. quiet.harbor.42@<domain>
    print(mailbox.expires_at)  # accepts mail for 24 hours

    signup(email=mailbox.address)  # your code under test

    message = client.wait_for_message(mailbox.address, subject="verify", timeout=60)
    print(message.from_, message.subject)
    print(message.code)  # best one-time code, or None
    print(message.confirm_link)  # best "confirm / sign in" link, or None

    client.mailboxes.delete(mailbox.address)

wait_for_message returns as soon as a matching message is there — including one that arrived before the call — and raises WaitTimeoutError when timeout seconds pass without one.

Async

AsyncFakeEmail has the same methods, awaited. It works with asyncio and trio.

import asyncio
from fake_email_pro import AsyncFakeEmail


async def main() -> None:
    async with AsyncFakeEmail() as client:
        mailbox = await client.mailboxes.create()
        await signup(email=mailbox.address)
        link = await client.wait_for_link(mailbox.address)
        print(link)
        async for message in client.messages.iter(mailbox.address):
            print(message.subject)


asyncio.run(main())

pytest: a fresh mailbox per test

# conftest.py
import contextlib

import pytest
from fake_email_pro import FakeEmail, NotFoundError


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


@pytest.fixture
def mailbox(fake_email: FakeEmail):
    mailbox = fake_email.mailboxes.create()
    yield mailbox
    with contextlib.suppress(NotFoundError):  # the test may have deleted it already
        fake_email.mailboxes.delete(mailbox.address)
# test_password_reset.py
def test_reset_email_has_a_code(fake_email, mailbox, app):
    app.request_password_reset(mailbox.address)

    code = fake_email.wait_for_code(mailbox.address, subject="reset", timeout=30)

    assert app.reset_password(mailbox.address, code, "n3w-passw0rd").ok

Each test gets its own address, so tests can run in parallel (pytest -n auto) without reading each other's mail. Every created mailbox spends one unit of the monthly quota; deleting it does not give the unit back, but keeps your mailbox list short.

Playwright: sign up with an emailed code

With pytest-playwright and the fixtures above:

from playwright.sync_api import Page, expect


def test_signup_with_otp(page: Page, fake_email, mailbox):
    page.goto("https://staging.example.com/signup")
    page.get_by_label("Email").fill(mailbox.address)
    page.get_by_role("button", name="Create account").click()

    code = fake_email.wait_for_code(mailbox.address, from_="no-reply@example.com")

    page.get_by_label("Verification code").fill(code)
    page.get_by_role("button", name="Verify").click()
    expect(page.get_by_text("Welcome")).to_be_visible()

For a magic link, open the URL instead:

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

Waiting for messages

The next message: after

Without after, any message of the mailbox counts. To wait for the next one, pass the id of the message you already have:

first = client.wait_for_message(mailbox.address)
trigger_resend()
second = client.wait_for_message(mailbox.address, after=first.id)

after also takes a time — an RFC 3339 string or a datetime — for "messages since moment X" by the server's clock. Prefer a message id: two messages in the same millisecond can't be told apart by time. A naive datetime is taken as local time.

Filters and match

client.wait_for_message(
    mailbox.address,
    from_="acme.example",  # case-insensitive substring of the sender address
    subject="verification code",  # case-insensitive substring of the subject
    match=lambda m: m.attachments_count > 0,  # any predicate over SimpleMessage
    timeout=90,
)

from_ and subject are applied by the server. A message that fails match is skipped and the wait goes on after it, until the deadline.

wait_for_code and wait_for_link wait for a message that has a code or a link and return it as a string. They take the same arguments as wait_for_message. A message without one (a welcome email that arrives first, say) is skipped.

code = client.wait_for_code(mailbox.address, subject="code")
link = client.wait_for_link(mailbox.address, subject="confirm")

The server ranks what it finds: message.code is its best guess, and the full message has all of them.

One request: messages.wait

client.messages.wait(address, timeout=30, after=..., from_=..., subject=...) is a single long-poll request (timeout whole seconds, 1–60). It returns the message, or None when nothing arrived in time. The helpers above loop over it for you.

Reading messages

page = client.messages.list(mailbox.address, size=50)  # newest first; Page[SimpleMessage]
for message in client.messages.iter(mailbox.address):  # every page
    print(message.created_at, message.subject)

full = client.messages.get(mailbox.address, message.id)  # DetailedMessage
full.html, full.text  # bodies (None if absent)
full.codes  # every code found, best first
full.links  # every link, best "confirm / sign in" first: Link(url, text)
full.attachments  # Attachment(id, content_type, file_name, size_bytes)

client.messages.delete(mailbox.address, message.id)

Attachments and raw EML

for attachment in full.attachments:
    content = client.messages.attachment(mailbox.address, full.id, attachment.id)
    content.data  # bytes, decoded
    content.content_type  # "application/pdf"
    content.file_name  # "invoice.pdf" (UTF-8 names decoded)

eml: bytes = client.messages.raw(mailbox.address, full.id)

import email

parsed = email.message_from_bytes(eml)

A message the server could not parse has body_state == "UNPARSED": its raw EML is the only way to read it.

Mailboxes, domains, limits

client.domains.list()  # [Domain(name=..., type="PUBLIC"), ...]
client.mailboxes.create(domain="example.org")  # random address on a domain
client.mailboxes.create(local_part="ci-runner-7", domain="example.org")  # exact address (plan permitting)

client.mailboxes.get(address)
client.mailboxes.list(page=0, size=20)  # Page[Mailbox], newest first
for mailbox in client.mailboxes.iter():  # every active mailbox
    client.mailboxes.delete(mailbox.address)

limits = client.limits.get()
limits.quota.limit, limits.quota.used, limits.quota.resets_at
limits.requests_per_minute, limits.concurrent_waits

A mailbox accepts mail for 24 hours; after that it and its messages are gone and every call on it raises NotFoundError. An address is never handed out twice.

Errors

Every exception derives from FakeEmailError. API errors are APIError subclasses with status_code, code (the server's error code, e.g. "address_taken"), message, body, headers and rate_limit.

Exception When
BadRequestError 400: an invalid parameter or body
AuthenticationError 401: missing, unknown, revoked or expired key
QuotaExhaustedError 402: the monthly mailbox quota is used up; has limit, used, resets_at, upgrade_url
PermissionDeniedError 403 plan_forbidden: the plan does not allow this (e.g. a custom local_part)
NotFoundError 404: no such mailbox (or it expired), message, attachment or domain
ConflictError 409 address_taken: that address was already issued
RateLimitError 429: code is rate_limit_exceeded or too_many_waits; has retry_after
InternalServerError 5xx
APIConnectionError, APITimeoutError no response: network failure or timeout
WaitTimeoutError a wait_for_* helper ran out of time (also a TimeoutError)
from fake_email_pro import ConflictError, QuotaExhaustedError

try:
    mailbox = client.mailboxes.create(local_part="ci-runner-7", domain="example.org")
except ConflictError:
    mailbox = client.mailboxes.create(domain="example.org")
except QuotaExhaustedError as e:
    raise SystemExit(f"Quota {e.used}/{e.limit}, renews {e.resets_at:%Y-%m-%d}: {e.upgrade_url}")

Retries and rate limits

The client retries up to max_retries times (default 2):

  • 429 (rate limit, too many concurrent waits) and 503 for any request — the server refuses these before doing anything, so repeating is safe;
  • 502, 504 and connection errors for GET and DELETE only — a POST that may have created a mailbox is never repeated.

It sleeps for Retry-After when the server sends it (capped at 60 s), otherwise backs off exponentially with jitter (0.5 s, 1 s, 2 s, … up to 8 s). After the last attempt the error is raised.

The rate limit is requests per minute per account, shared by all your keys; wait requests count once however long they are held open. error.rate_limit has the window state from the X-RateLimit-* headers (limit, remaining, reset_at). Waits held open at once are capped at limits.concurrent_waits: run fewer parallel workers than that, or let the retries absorb the occasional too_many_waits.

Configuration

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 gets its own timeout + 10 s
    max_retries=2,  # 0 disables retries
    user_agent="my-e2e-suite/1.4",  # prepended to fake-email-pro-python/<version>
    http_client=httpx.Client(proxy="http://proxy.internal:3128"),  # proxies, transports, event hooks
)

AsyncFakeEmail takes the same arguments, with http_client=httpx.AsyncClient(...). A client you pass in is not closed by close() — you own it. Use the client as a context manager (with / async with) or call close() to release connections.

Requirements

Python 3.9 to 3.13 and httpx 0.25 or newer. The package is fully typed and checked with mypy --strict.

License

MIT © fake-email.pro

Metadata

Release files for fake-email-pro 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 fake-email-pro 0.1.0
File Size Uploaded Provenance Actions
fake_email_pro-0.1.0.tar.gz 42.1 kB With provenance Details for fake_email_pro-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fake-email-pro 0.1.0
File Interpreter ABI Platform Actions
fake_email_pro-0.1.0-py3-none-any.whl Python 3 none any Details for fake_email_pro-0.1.0-py3-none-any.whl

Total release size: 65.2 kB

Release files / fake_email_pro-0.1.0.tar.gz

Download URL fake_email_pro-0.1.0.tar.gz
Size 42.1 kB
Tags Source
SHA-256 checksum
How to use checksums
21dcfceef41f6eab6405a8cf36e60a84d049ed864e042cc1ddf05c3b0197b892
BLAKE2b-256 checksum
How to use checksums
3a195fdbb9364a148fd4c6f1a8abe6185577318fc55e070eaaec0219c15d96c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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

Download URL fake_email_pro-0.1.0-py3-none-any.whl
Size 23.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
017029cc002182adbad1aab5729c676a4cc872d949bb7e28c6bc5590f1ed3ada
BLAKE2b-256 checksum
How to use checksums
28f044c5286788c0da3b523d1ac5ab510b883eedbd937cb585b4a41e4296a780
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for fake-email-pro 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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fake_email_pro-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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 Full 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