Receive and test email with Python

An email test needs its own recipient address and a bounded wait for the message your application sends. This guide uses mailslurp-client to create an inbox, receive that message and inspect it in Python. For screenshots in real mail clients, use the Python device-rendering example.

Quick links

Task	Start here
Install and receive an email	Get started
Render an email in Gmail, Outlook or Apple Mail	Python render example and target selection
Find a Python method and its arguments	Python method reference
Find current HTTP endpoints and request fields	REST API reference
Find runnable projects	Device rendering, Python unittest and Django with Playwright
Check the installed SDK release	PyPI package

The Python SDK reference documents the generated client. The examples below follow a test from inbox creation to cleanup; keep the returned IDs for each subsequent step.

Get started

Create API Key

Copy an API key from the MailSlurp dashboard. Store it in your environment as MAILSLURP_API_KEY. For an organization or a support-provided demo, use the key belonging to that account.

Install package

Use a Python 3 virtual environment and install the official package:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade mailslurp-client
python -m pip show mailslurp-client

On Windows, activate the environment with .venv\Scripts\activate. Pin the version you validate in your project's dependency file.

Configure

This complete script creates an inbox and prints its ID and address:

import os
import mailslurp_client

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = os.environ["MAILSLURP_API_KEY"]

with mailslurp_client.ApiClient(configuration) as api_client:
    inboxes = mailslurp_client.InboxControllerApi(api_client)
    inbox = inboxes.create_inbox_with_defaults()
    print("Inbox ID:", inbox.id)
    print("Send your test email to:", inbox.email_address)

Keep controller calls inside the ApiClient context so its connection pool stays open. Use the address returned by the API; its domain depends on your account and inbox configuration.

Email usage examples

Receive email

Send an email from the application you are testing to the address above. Set MAILSLURP_INBOX_ID to the returned inbox ID, then run:

import os
import mailslurp_client

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = os.environ["MAILSLURP_API_KEY"]

with mailslurp_client.ApiClient(configuration) as api_client:
    waiting = mailslurp_client.WaitForControllerApi(api_client)
    email = waiting.wait_for_latest_email(
        inbox_id=os.environ["MAILSLURP_INBOX_ID"],
        timeout=30000,
        unread_only=True,
        _request_timeout=40,
    )
    assert email.id
    print(email.subject)
    print(email.body)

The API waits up to 30 seconds; the HTTP timeout is longer so the client can receive its response. Reuse email.id for subsequent message inspection or a render. For repeated test runs, use a new inbox per test or match the expected message as described in waiting for email.

Create an email address with options

Inside an open ApiClient context, use CreateInboxDto to name an inbox:

inboxes = mailslurp_client.InboxControllerApi(api_client)
inbox = inboxes.create_inbox_with_options(
    mailslurp_client.CreateInboxDto(name="Checkout test")
)

Send emails

For an account with sending enabled, use the inbox controller inside the same context:

inboxes.send_email(
    inbox.id,
    mailslurp_client.SendEmailOptions(
        to=[os.environ["TEST_RECIPIENT"]],
        subject="Order confirmation",
        body="<h1>Thank you for your order</h1>",
        is_html=True,
    ),
)

See sending and receiving email for message options and attachments for uploads and downloads. Use SMTP and IMAP access when your application expects a mail server instead of an HTTP API.

Delete an inbox

Delete disposable test inboxes after your assertions and artifact downloads finish:

inboxes.delete_inbox(inbox_id=inbox.id)

For automated cleanup and parallel test isolation, see test resource lifecycle.

Device rendering

The Python device-rendering project accepts an HTML file or the email.id from your wait. It selects exact clients, waits for completion, downloads screenshots and creates a local HTML gallery. Its wait and results commands can inspect an existing run without creating another one. See the CI walkthrough for commands and account access and target coverage before running a larger batch.

The rendering project uses Python's standard HTTP library with the current REST API. This keeps target selection, imports and long polling independent of the device-preview methods available in an installed SDK release.

SDK Documentation

Use the Python method reference for published controller methods and the REST reference for current endpoints. If a hosted controller page is missing, use the generated Python reference files on GitHub. Select the tag matching your installed SDK version before copying method names or arguments.

For a visual introduction, watch the Python email tutorial. For message waits, OTPs, links and CI assertions, continue with integration testing.