# 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
[](https://youtu.be/tcLJ3xX-H88)
## Quick links
- [API documentation](https://docs.mailslurp.com/api/)
- [Method Documentation](https://python.mailslurp.com/)
- [PyPI Package](https://pypi.org/project/mailslurp-client/)
- [Github Source](https://github.com/mailslurp/mailslurp-client-python)
- [Send email using SMTP in Python](https://www.mailslurp.com/smtp/python-send-email-smtp/)
- [SMTP access details](https://www.mailslurp.com/guides/smtp-imap/)
## Get started
This section describes how to get up and running with the Python client.
See the [examples page](https://www.mailslurp.com/examples/) for more examples and use with common frameworks such as Django, Flask and Pytest.
See the method documentation for a [list of all functions](https://python.mailslurp.com/) or jump to common controllers below:
- [InboxController](https://python.mailslurp.com/api/inbox_controller_api.html)
- [EmailController](https://python.mailslurp.com/api/email_controller_api.html)
- [SMSController](https://python.mailslurp.com/api/sms_controller_api.html)
- [WaitForController](https://python.mailslurp.com/api/wait_for_controller_api.html)
### Create API Key
First you'll need an API Key. [Create a free account](https://app.mailslurp.com) 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.
```bash
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:
```bash
pip install python-certifi-win32
```
### Configure
Once installed you can import `mailslurp_client` and create a [configuration](https://python.mailslurp.com/configuration.html) with your [API Key](https://app.mailslurp.com).
```python
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:
```python
with mailslurp_client.ApiClient(configuration) as api_client:
api_instance = mailslurp_client.InboxControllerApi(api_client)
```
See the [controllers overview](https://python.mailslurp.com/api/index.html) 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:
```python
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:
```python
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](https://python.mailslurp.com/api/inbox_controller_api.html) for more methods.
### Access inbox using SMTP
```python
smtp_access = inbox_controller.get_imap_smtp_access(inbox_id=inbox.id)
self.assertIsNotNone(smtp_access.secure_smtp_server_host)
```
### Send with SMTP client
```python
# 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](https://python.mailslurp.com/api/inbox_controller_api.html):
```python
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
```python
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
```python
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.
```python
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](https://python.mailslurp.com/api/inbox_controller_api.html):
```python
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](https://python.mailslurp.com/api/wait_for_controller_api.html) to wait for an expected email count to be satisfied and then return those emails.
```python
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
```python
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
```python
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
```python
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.
```python
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](https://www.mailslurp.com/guides/) or [the examples](https://www.github.com/mailslurp/examples) or the [Method Documentation](https://python.mailslurp.com/) for full usage.
Raw data
{
"_id": null,
"home_page": "https://www.mailslurp.com/python",
"name": "mailslurp-client",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "MailSlurp, Email, SMTP, Mailer, MailSlurp API, Test",
"author": "MailSlurp",
"author_email": "contact@mailslurp.dev",
"download_url": "https://files.pythonhosted.org/packages/54/b2/4e212aa452a10bb83355e24078fbeed57641a370a3e7bae55921157b3a9b/mailslurp-client-15.19.22.tar.gz",
"platform": null,
"description": "\n# MailSlurp Python Client\n\n> Create real email addresses on demand. Send and receive emails and attachments from code and tests using Python.\n\nMailSlurp 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.\n\n## Video tutorial\n\n[](https://youtu.be/tcLJ3xX-H88)\n\n## Quick links\n\n- [API documentation](https://docs.mailslurp.com/api/)\n- [Method Documentation](https://python.mailslurp.com/)\n- [PyPI Package](https://pypi.org/project/mailslurp-client/)\n- [Github Source](https://github.com/mailslurp/mailslurp-client-python)\n- [Send email using SMTP in Python](https://www.mailslurp.com/smtp/python-send-email-smtp/)\n- [SMTP access details](https://www.mailslurp.com/guides/smtp-imap/)\n\n## Get started\n\nThis section describes how to get up and running with the Python client.\n\nSee the [examples page](https://www.mailslurp.com/examples/) for more examples and use with common frameworks such as Django, Flask and Pytest.\n\nSee the method documentation for a [list of all functions](https://python.mailslurp.com/) or jump to common controllers below:\n\n- [InboxController](https://python.mailslurp.com/api/inbox_controller_api.html)\n- [EmailController](https://python.mailslurp.com/api/email_controller_api.html)\n- [SMSController](https://python.mailslurp.com/api/sms_controller_api.html)\n- [WaitForController](https://python.mailslurp.com/api/wait_for_controller_api.html)\n\n### Create API Key\n\nFirst you'll need an API Key. [Create a free account](https://app.mailslurp.com) and copy the key from your dashboard.\n\n### Install package\n\nMailSlurp has an official PyPI package called `mailslurp-client`. It supports Python version 2 and 3.\n\n```bash\npip install mailslurp-client\n```\n\nOn 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:\n\n```bash\npip install python-certifi-win32\n```\n\n### Configure\n\nOnce installed you can import `mailslurp_client` and create a [configuration](https://python.mailslurp.com/configuration.html) with your [API Key](https://app.mailslurp.com).\n\n```python\nimport mailslurp_client\n\nconfiguration = mailslurp_client.Configuration()\nconfiguration.api_key[\"x-api-key\"] = YOUR_API_KEY\n```\n\nThen you can create API controller instances using the configuration:\n\n```python\nwith mailslurp_client.ApiClient(configuration) as api_client:\n api_instance = mailslurp_client.InboxControllerApi(api_client)\n\n```\n\nSee the [controllers overview](https://python.mailslurp.com/api/index.html) for all API methods.\n\n## Email usage examples\n\nMailSlurp can be used to create email addresses than can send and receive real emails, SMS, and attachments in Python. \n\n### Create an email address\nCreate an inbox using the inbox controller:\n\n```python\ninbox_controller = mailslurp_client.InboxControllerApi(api_client)\ninbox = inbox_controller.create_inbox_with_defaults()\nself.assertTrue(\"@mailslurp\" in inbox.email_address)\n```\n\nYou can pass options using the `CreateInboxOptions` class:\n\n```python\noptions = mailslurp_client.CreateInboxDto()\noptions.name = \"Test inbox\"\noptions.inbox_type = \"SMTP_INBOX\"\ninbox = inbox_controller.create_inbox_with_options(options)\nself.assertTrue(\"@mailslurp\" in inbox.email_address)\n```\n\nSee the [inbox controller](https://python.mailslurp.com/api/inbox_controller_api.html) for more methods.\n\n### Access inbox using SMTP\n\n```python\nsmtp_access = inbox_controller.get_imap_smtp_access(inbox_id=inbox.id)\nself.assertIsNotNone(smtp_access.secure_smtp_server_host)\n```\n\n### Send with SMTP client\n\n```python\n# configure smtp client using access details\nfrom smtplib import SMTP\n\nwith SMTP(\n host=smtp_access.secure_smtp_server_host,\n port=smtp_access.secure_smtp_server_port,\n) as smtp:\n msg = \"Subject: Test subject\n\nThis is the body\"\n smtp.login(\n user=smtp_access.secure_smtp_username,\n password=smtp_access.secure_smtp_password,\n )\n smtp.sendmail(\n from_addr=inbox.email_address,\n to_addrs=[inbox.email_address],\n msg=msg,\n )\n smtp.quit()\n```\n\n### List inboxes\n\nList inboxes using the [inbox controller](https://python.mailslurp.com/api/inbox_controller_api.html):\n\n```python\ninboxes = inbox_controller.get_all_inboxes(page=0)\n\n# pagination properties\nself.assertTrue(inboxes.total_pages > 0)\nself.assertTrue(inboxes.total_elements > 0)\n\n# view contents\nself.assertIsNotNone(inboxes.content[0].email_address)\n```\n\n### Get an inbox\n\n```python\ninbox = inbox_controller.get_inbox(inbox_id=inbox.id)\nself.assertTrue(\"@mailslurp\" in inbox.email_address)\n\n# get by email address\ninbox_by_email = inbox_controller.get_inbox_by_email_address(\n inbox.email_address\n)\nself.assertTrue(inbox_by_email.exists)\n\n# get by name\ninbox_by_name = inbox_controller.get_inbox_by_name(inbox.name)\nself.assertTrue(inbox_by_name.exists)\n```\n\n### Delete an inbox\n\n```python\ninbox_controller.delete_inbox(inbox_id=inbox.id)\n```\n\n### Upload attachments\nTo send attachments first upload the attachments as base64 encoded strings and use the returned attachment IDs when sending.\n\n```python\nimport base64\n\nattachment_controller = mailslurp_client.AttachmentControllerApi(api_client)\noptions = mailslurp_client.UploadAttachmentOptions(\n filename=\"test.txt\",\n content_type=\"text/plain\",\n base64_contents=base64.b64encode(\"Hello world\".encode(\"utf-8\")).decode(\n \"utf-8\"\n ),\n)\nattachment_ids = attachment_controller.upload_attachment(options)\nself.assertTrue(len(attachment_ids) == 1)\n```\n\n### Send emails\nSend emails with the [inbox controller](https://python.mailslurp.com/api/inbox_controller_api.html):\n\n```python\nsend_options = mailslurp_client.SendEmailOptions(\n to=[recipient.email_address],\n subject=\"Hello\",\n body=\"Here is your email body\",\n attachments=attachment_ids,\n)\nsent = inbox_controller.send_email_and_confirm(\n inbox_id=inbox.id, send_email_options=send_options\n)\nself.assertTrue(sent.sent_at is not None)\n```\n\n### Receive emails and extract content\nUse the [wait for controller](https://python.mailslurp.com/api/wait_for_controller_api.html) to wait for an expected email count to be satisfied and then return those emails.\n\n\n```python\nwait_for_controller = mailslurp_client.WaitForControllerApi(api_client)\nemail = wait_for_controller.wait_for_latest_email(\n inbox_id=inbox.id, timeout=60_000, unread_only=True\n)\nself.assertTrue(\"Hello\" in email.subject)\n```\n\n### Email content matching\n\n```python\nmatching_emails = wait_for_controller.wait_for_matching_emails(\n inbox_id=inbox.id,\n timeout=60_000,\n unread_only=False,\n match_options=mailslurp_client.MatchOptions(\n conditions=[\n mailslurp_client.ConditionOption(\n condition=\"HAS_ATTACHMENTS\", value=\"TRUE\"\n )\n ],\n matches=[\n mailslurp_client.MatchOption(\n field=\"SUBJECT\", should=\"CONTAIN\", value=\"Hello\"\n )\n ],\n ),\n count=1,\n)\nself.assertTrue(len(matching_emails) > 0)\n```\n\n### Download attachments\n\n```python\nattachment_content = attachment_controller.download_attachment_as_base64_encoded(email.attachments[0])\nattachment_metadata = attachment_controller.get_attachment_info(email.attachments[0])\nself.assertEqual(attachment_metadata.content_type, \"text/plain\")\n```\n\n### Fetch email by ID\n\n```python\nemail_controller = mailslurp_client.EmailControllerApi(api_client)\nemail = email_controller.get_email(email_id=email_id)\nself.assertTrue(\"Hello\" in email.subject)\n```\n\n### Verify email address\n\nYou can verify email addresses with MailSlurp. This will perform SMTP queries for the email address on your behalf.\n\n```python\ndef test_validate_email(self):\n with mailslurp_client.ApiClient(configuration) as api_client:\n mailserver_controller = mailslurp_client.MailServerControllerApi(api_client)\n verify_options = mailslurp_client.VerifyEmailAddressOptions(email_address=\"test@gmail.com\")\n result = mailserver_controller.verify_email_address(verify_options=verify_options)\n assert result.error is None\n assert result.is_valid is True\n```\n\n## SDK Documentation\n\nSee the [guides page](https://www.mailslurp.com/guides/) or [the examples](https://www.github.com/mailslurp/examples) or the [Method Documentation](https://python.mailslurp.com/) for full usage. \n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Official MailSlurp Python SDK Email API",
"version": "15.19.22",
"project_urls": {
"Homepage": "https://www.mailslurp.com/python"
},
"split_keywords": [
"mailslurp",
" email",
" smtp",
" mailer",
" mailslurp api",
" test"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c13779aa266cb89e8d05d5e9f7e2a1299ff53e2fb92f45170cdf46e63e159b9",
"md5": "198727d75f4be2a6b8f961869d19d440",
"sha256": "8037e719927b0b54cde4a6bb19e19e698ad69527b6a4ee71691ab2d0fedf0ef1"
},
"downloads": -1,
"filename": "mailslurp_client-15.19.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "198727d75f4be2a6b8f961869d19d440",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 774998,
"upload_time": "2024-06-03T06:06:03",
"upload_time_iso_8601": "2024-06-03T06:06:03.323118Z",
"url": "https://files.pythonhosted.org/packages/2c/13/779aa266cb89e8d05d5e9f7e2a1299ff53e2fb92f45170cdf46e63e159b9/mailslurp_client-15.19.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "54b24e212aa452a10bb83355e24078fbeed57641a370a3e7bae55921157b3a9b",
"md5": "d64572e798067c93c2a5f4abe6302e1f",
"sha256": "4c6b3329f9088545ccf69c4f9f93c2dab391a6f3808fd4e1623b1e45dbe1ec1d"
},
"downloads": -1,
"filename": "mailslurp-client-15.19.22.tar.gz",
"has_sig": false,
"md5_digest": "d64572e798067c93c2a5f4abe6302e1f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 341342,
"upload_time": "2024-06-03T06:06:11",
"upload_time_iso_8601": "2024-06-03T06:06:11.087924Z",
"url": "https://files.pythonhosted.org/packages/54/b2/4e212aa452a10bb83355e24078fbeed57641a370a3e7bae55921157b3a9b/mailslurp-client-15.19.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-03 06:06:11",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mailslurp-client"
}
JSON