testlie

Python client for Testlie: disposable email inboxes for end-to-end tests, waiting for an email, and pulling one-time codes and magic links out of it. Standard library only (urllib), Python 3.9+, typed, with a pytest plugin.

30-second quick start

1. Sign up at testlie.com (free plan) and create a key on the API keys page.
2. Install and point the client at it:

pip install testlie
export TESTLIE_API_KEY=tl_...                # a read-only key can wait and extract
# export TESTLIE_URL=https://testlie.example  # only for a self-hosted server

3. Use it in a test:

from testlie import Testlie

testlie = Testlie()  # TESTLIE_API_KEY, TESTLIE_URL

with testlie.disposable_inbox(minutes=15) as inbox:
    # inbox.smtp has host, ports, username and password for your app's SMTP settings
    sign_up(email=inbox.address("alice"))          # <alias>+alice@<inbound domain>
    email = testlie.wait_for_email(inbox.id, to=inbox.address("alice"), subject="Confirm", timeout=60)
    code = testlie.extract_otp(email)              # "482913"
    link = testlie.extract_link(email, "verify")   # first magic link or link containing "verify"

Records returned by the API are dicts that also allow attribute access (inbox.id, inbox["smtp"]["password"]).

API

m is a message ID or a message dict. timeout is in seconds; waits over two minutes are split into several long-polls. pattern is a compiled regex or a case-insensitive substring, matched against magic links first, then every link, on the URL and the link text.

Errors: TestlieError (status, code, upgrade_url, body; status 0 for network errors), TestlieTimeoutError (408) and TestlieExtractError. GET, PUT and DELETE are retried on 429, 5xx and network errors with exponential backoff, honouring Retry-After.

pytest

The plugin is registered automatically when the package is installed.

def test_signup_sends_code(testlie, testlie_inbox, page):
    address = testlie_inbox.address("signup")
    page.goto("/signup"); page.fill("#email", address); page.click("text=Sign up")
    email = testlie.wait_for_email(testlie_inbox.id, to=address, subject="code")
    page.fill("#code", testlie.extract_otp(email))

• testlie: session-wide client.
• testlie_inbox: a fresh disposable inbox per test, deleted afterwards.
• --testlie-url URL overrides TESTLIE_URL; the ini option testlie_inbox_minutes (default 30) sets the inbox lifetime.

Development

pip install -e . pytest
pytest                     # uses a local http.server fake of the API
python -m build && twine check dist/*

Links

• Documentation: https://testlie.com/docs/sdks
• REST API: https://testlie.com/docs/api
• Issues: https://github.com/carriergrade/testlie-sdk/issues
• Changelog: CHANGELOG.md

MIT licensed. Copyright (c) 2026 Carrier Grade Inc.