MailSlurp Python Client

Create real email addresses on demand. Send and receive emails and attachments from code and tests using Python.

MailSlurp is an email API service that lets you create real email addresses in code. You can then send and receive emails and attachments in Python applications and tests.

Video tutorial

Quick links

Get started

This section describes how to get up and running with the Python client.

See the examples page for more examples and use with common frameworks such as Django, Flask and Pytest.

See the method documentation for a list of all functions or jump to common controllers below:

Create API Key

First you'll need an API Key. Create a free account and copy the key from your dashboard.

Install package

MailSlurp has an official PyPI package called mailslurp-client. It supports Python version 2 and 3.

pip install mailslurp-client

On some systems you may need to install distutils. If you encounter a CERTIFICATE_VERIFY_VALID error you can install certifi and certifi-win32 for Windows:

pip install python-certifi-win32

Configure

Once installed you can import mailslurp_client and create a configuration with your API Key.

import mailslurp_client

configuration = mailslurp_client.Configuration()
configuration.api_key["x-api-key"] = YOUR_API_KEY

Then you can create API controller instances using the configuration:

with mailslurp_client.ApiClient(configuration) as api_client:
    api_instance = mailslurp_client.InboxControllerApi(api_client)

See the controllers overview for all API methods.

Email usage examples

MailSlurp can be used to create email addresses than can send and receive real emails, SMS, and attachments in Python.

Create an email address

Create an inbox using the inbox controller:

inbox_controller = mailslurp_client.InboxControllerApi(api_client)
inbox = inbox_controller.create_inbox_with_defaults()
self.assertTrue("@mailslurp" in inbox.email_address)

You can pass options using the CreateInboxOptions class:

options = mailslurp_client.CreateInboxDto()
options.name = "Test inbox"
options.inbox_type = "SMTP_INBOX"
inbox = inbox_controller.create_inbox_with_options(options)
self.assertTrue("@mailslurp" in inbox.email_address)

See the inbox controller for more methods.

Access inbox using SMTP

smtp_access = inbox_controller.get_imap_smtp_access(inbox_id=inbox.id)
self.assertIsNotNone(smtp_access.secure_smtp_server_host)

Send with SMTP client

# configure smtp client using access details
from smtplib import SMTP

with SMTP(
    host=smtp_access.secure_smtp_server_host,
    port=smtp_access.secure_smtp_server_port,
) as smtp:
    msg = "Subject: Test subject

This is the body"
    smtp.login(
        user=smtp_access.secure_smtp_username,
        password=smtp_access.secure_smtp_password,
    )
    smtp.sendmail(
        from_addr=inbox.email_address,
        to_addrs=[inbox.email_address],
        msg=msg,
    )
    smtp.quit()

List inboxes

List inboxes using the inbox controller:

inboxes = inbox_controller.get_all_inboxes(page=0)

# pagination properties
self.assertTrue(inboxes.total_pages > 0)
self.assertTrue(inboxes.total_elements > 0)

# view contents
self.assertIsNotNone(inboxes.content[0].email_address)

Get an inbox

inbox = inbox_controller.get_inbox(inbox_id=inbox.id)
self.assertTrue("@mailslurp" in inbox.email_address)

# get by email address
inbox_by_email = inbox_controller.get_inbox_by_email_address(
    inbox.email_address
)
self.assertTrue(inbox_by_email.exists)

# get by name
inbox_by_name = inbox_controller.get_inbox_by_name(inbox.name)
self.assertTrue(inbox_by_name.exists)

Delete an inbox

inbox_controller.delete_inbox(inbox_id=inbox.id)

Upload attachments

To send attachments first upload the attachments as base64 encoded strings and use the returned attachment IDs when sending.

import base64

attachment_controller = mailslurp_client.AttachmentControllerApi(api_client)
options = mailslurp_client.UploadAttachmentOptions(
    filename="test.txt",
    content_type="text/plain",
    base64_contents=base64.b64encode("Hello world".encode("utf-8")).decode(
        "utf-8"
    ),
)
attachment_ids = attachment_controller.upload_attachment(options)
self.assertTrue(len(attachment_ids) == 1)

Send emails

Send emails with the inbox controller:

send_options = mailslurp_client.SendEmailOptions(
    to=[recipient.email_address],
    subject="Hello",
    body="Here is your email body",
    attachments=attachment_ids,
)
sent = inbox_controller.send_email_and_confirm(
    inbox_id=inbox.id, send_email_options=send_options
)
self.assertTrue(sent.sent_at is not None)

Receive emails and extract content

Use the wait for controller to wait for an expected email count to be satisfied and then return those emails.

wait_for_controller = mailslurp_client.WaitForControllerApi(api_client)
email = wait_for_controller.wait_for_latest_email(
    inbox_id=inbox.id, timeout=60_000, unread_only=True
)
self.assertTrue("Hello" in email.subject)

Email content matching

matching_emails = wait_for_controller.wait_for_matching_emails(
    inbox_id=inbox.id,
    timeout=60_000,
    unread_only=False,
    match_options=mailslurp_client.MatchOptions(
        conditions=[
            mailslurp_client.ConditionOption(
                condition="HAS_ATTACHMENTS", value="TRUE"
            )
        ],
        matches=[
            mailslurp_client.MatchOption(
                field="SUBJECT", should="CONTAIN", value="Hello"
            )
        ],
    ),
    count=1,
)
self.assertTrue(len(matching_emails) > 0)

Download attachments

attachment_content = attachment_controller.download_attachment_as_base64_encoded(email.attachments[0])
attachment_metadata = attachment_controller.get_attachment_info(email.attachments[0])
self.assertEqual(attachment_metadata.content_type, "text/plain")

Fetch email by ID

email_controller = mailslurp_client.EmailControllerApi(api_client)
email = email_controller.get_email(email_id=email_id)
self.assertTrue("Hello" in email.subject)

Verify email address

You can verify email addresses with MailSlurp. This will perform SMTP queries for the email address on your behalf.

def test_validate_email(self):
    with mailslurp_client.ApiClient(configuration) as api_client:
        mailserver_controller = mailslurp_client.MailServerControllerApi(api_client)
        verify_options = mailslurp_client.VerifyEmailAddressOptions(email_address="test@gmail.com")
        result = mailserver_controller.verify_email_address(verify_options=verify_options)
        assert result.error is None
        assert result.is_valid is True

SDK Documentation

See the guides page or the examples or the Method Documentation for full usage.

Release files for mailslurp-client 17.5.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 mailslurp-client 17.5.0
File	Size	Uploaded
mailslurp_client-17.5.0.tar.gz	647.9 kB	Mar 31, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mailslurp-client 17.5.0
File	Interpreter	ABI	Platform	Reset
mailslurp_client-17.5.0-py3-none-any.whl 1.4 MB Mar 31, 2026	Python 3	none	any	Details

Total release size: 2.1 MB

Release files / mailslurp_client-17.5.0.tar.gz

Download URL	mailslurp_client-17.5.0.tar.gz
Size	647.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`212ea4355d497e3c2e9003eaff4aca671f30ca2ad13c15c7282af48ff5b37fa4`
BLAKE2b-256 checksum How to use checksums	`68ab0f69fe25f2d4e7a71b9f25c16a74dc36a387dc42cabfef59114f78ed0130`
Upload date	Mar 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.8.6`

Release files / mailslurp_client-17.5.0-py3-none-any.whl

Download URL	mailslurp_client-17.5.0-py3-none-any.whl
Size	1.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`c4f9674e9b1ec7d7660dd2fe4676e50729e35af432496572e5fa219660a40b16`
BLAKE2b-256 checksum How to use checksums	`7bbe41eaee1d804f892d430a2db816576d3dc4a996fb2af1999b5236a5e3521d`
Upload date	Mar 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.8.6`