# 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](https://github.com/mailslurp/examples/tree/master/python-device-render).

## Quick links

| Task | Start here |
| --- | --- |
| Install and receive an email | [Get started](#get-started) |
| Render an email in Gmail, Outlook or Apple Mail | [Python render example](/docs/device-rendering-ci/#python) and [target selection](/docs/device-rendering-profiles/) |
| Find a Python method and its arguments | [Python method reference](https://python.mailslurp.com/) |
| Find current HTTP endpoints and request fields | [REST API reference](/docs/api/) |
| Find runnable projects | [Device rendering](https://github.com/mailslurp/examples/tree/master/python-device-render), [Python unittest](https://github.com/mailslurp/examples/tree/master/python3-pyunit) and [Django with Playwright](https://github.com/mailslurp/examples/tree/master/python3-django-playwright) |
| Check the installed SDK release | [PyPI package](https://pypi.org/project/mailslurp-client/) |

The [Python SDK reference](/docs/python/) 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](https://app.mailslurp.com). 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:

```bash
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:

```python
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:

```python
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](/docs/wait-for/).

### Create an email address with options

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

```python
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:

```python
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](/docs/emails/) for message options and [attachments](/docs/attachments/) for uploads and downloads. Use [SMTP and IMAP access](/docs/imap-smtp/) 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:

```python
inboxes.delete_inbox(inbox_id=inbox.id)
```

For automated cleanup and parallel test isolation, see [test resource lifecycle](/docs/test-resource-lifecycle/).

## Device rendering

The [Python device-rendering project](https://github.com/mailslurp/examples/tree/master/python-device-render) 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](/docs/device-rendering-ci/#python) for commands and [account access and target coverage](/docs/device-rendering-profiles/) 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](https://python.mailslurp.com/) for published controller methods and the [REST reference](/docs/api/) for current endpoints. If a hosted controller page is missing, use the [generated Python reference files on GitHub](https://github.com/mailslurp/mailslurp-client-python/tree/master/docs). Select the tag matching your installed SDK version before copying method names or arguments.

For a visual introduction, watch the [Python email tutorial](https://youtu.be/tcLJ3xX-H88). For message waits, OTPs, links and CI assertions, continue with [integration testing](/docs/testing/).