/python Temp Email API

Verifying email flows in Python — Django or Flask signups, password resets, OTP logins — usually stalls because the confirmation email lands in a mailbox pytest can't see. The OpenInbox API gives each test a disposable inbox over plain HTTP: create it, trigger the flow, poll, and pull the code out of the body. This guide uses httpx (requests works identically) and a pytest fixture, all against the real API.

How the flow works

• Create a disposable inbox: POST /api/inbox (no auth) → {"id", "email", "expiresAt"}.
• Use that address in your signup/reset flow so your app emails it.
• Poll GET /api/inbound/api/emails?inboxEmail=<email> with the X-API-KEY header until an email arrives.
• re.search a 4–8 digit code (or URL) in the email textBody.
• Submit the code / visit the link and assert.

Setup

Install httpx (or requests) and pytest. Reading the inbox is a premium endpoint, so read the key from the environment rather than hard-coding it.

pip install httpx pytest

export OPENINBOX_API_KEY="your-premium-api-key"

A reusable OpenInbox client

Wrap the two calls you need. create_inbox creates a fresh inbox; wait_for_otp polls the inbox and returns the first 4–8 digit code it finds in textBody.

import os, re, time, httpx

BASE = "https://api.openinbox.io/api"
HEADERS = {"X-API-KEY": os.environ["OPENINBOX_API_KEY"]}


def create_inbox() -> dict:
    """Create a disposable inbox (no auth required)."""
    res = httpx.post(f"{BASE}/inbox")
    res.raise_for_status()
    return res.json()  # {"id", "email", "expiresAt", ...}


def wait_for_otp(inbox_email: str, timeout: int = 30) -> str:
    """Poll until an email arrives, then return the OTP from textBody."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        res = httpx.get(
            f"{BASE}/inbound/api/emails",
            params={"inboxEmail": inbox_email},
            headers=HEADERS,
        )
        emails = res.json().get("emails", [])
        if emails:
            match = re.search(r"\b\d{4,8}\b", emails[0].get("textBody") or "")
            if match:
                return match.group(0)
        time.sleep(2)
    raise TimeoutError("No OTP email arrived in time")

A pytest integration test

A fixture gives every test a fresh inbox. The test triggers your signup, waits for the code, and asserts it looks like an OTP — extend it to drive your verify endpoint end to end.

import httpx, pytest
from openinbox import create_inbox, wait_for_otp


@pytest.fixture
def inbox():
    return create_inbox()


def test_signup_sends_otp(inbox):
    # Trigger your app so it emails the verification code
    httpx.post(
        "https://staging.yourapp.com/api/register",
        json={"email": inbox["email"], "password": "Str0ng!Pass"},
    )

    otp = wait_for_otp(inbox["email"])
    assert otp.isdigit() and 4 <= len(otp) <= 8

    # …submit otp to your verify endpoint and assert the success state

Async (httpx.AsyncClient)

For suites that create many inboxes at once, the same calls work with httpx.AsyncClient inside async def tests (with pytest-asyncio): await client.post(f"{BASE}/inbox") to create and await client.get(...) with the X-API-KEY header to poll. The endpoints and the textBody field are identical.