Asyncio SMTP Client

5.1.0 · active · verified Mon Apr 06

aiosmtplib is an asynchronous SMTP client for use with asyncio. It provides an async version of Python's `smtplib` module with similar APIs, enabling non-blocking email sending and interaction with SMTP servers. The current version is 5.1.0, and the project actively maintains compatibility with recent Python versions while introducing new features like XOAUTH2 authentication.

Warnings

breaking Python 3.9 support was dropped in v5.0.0. Earlier versions (v4.0.0, v3.0.0) also dropped support for Python 3.8 and 3.7 respectively. Ensure your environment meets the `requires_python >=3.10` for v5.x.x.
Fix: Upgrade your Python interpreter to 3.10 or newer, or pin `aiosmtplib` to an older version compatible with your Python environment (e.g., `aiosmtplib<5` for Python 3.9).
breaking In v3.0.0, argument handling for `SMTP` initialization and `connect()` changed significantly. Positional arguments became positional-only, and keyword arguments became keyword-only. Additionally, the `source_address` argument now requires a `(addr, port)` tuple instead of a string, and `local_hostname` should be used for the EHLO/HELO message hostname.
Fix: Review API calls, explicitly use keyword arguments where applicable, and update `source_address` to a `(addr, port)` tuple. Use `local_hostname` for the client's EHLO/HELO identifier.
gotcha When connecting, carefully distinguish between `use_tls=True` (for direct TLS/SSL on ports like 465) and `start_tls=True` (for upgrading a plaintext connection to TLS, typically on port 587 after connecting). Incorrectly combining these, e.g., `use_tls=True` for a STARTTLS-only server, can lead to connection errors.
Fix: For direct TLS/SSL (e.g., port 465), set `use_tls=True`. For STARTTLS (e.g., port 587), connect normally then call `await client.starttls()`, or rely on `aiosmtplib`'s default auto-upgrade behavior for STARTTLS if `start_tls` is not explicitly `False`.
gotcha SMTP is a sequential protocol. While `aiosmtplib` is asynchronous, executing multiple `send_message()` calls in parallel with a *single* `SMTP` client instance (e.g., using `asyncio.gather`) will not be more efficient than sequential execution, as the client must wait for one mail to be sent before starting the next. Consider creating multiple `SMTP` instances for parallel sending if high throughput is needed.
Fix: If sending many emails concurrently, create and manage multiple `aiosmtplib.SMTP` client instances, each handling a subset of emails, to achieve true parallel processing.

Install

pip install aiosmtplib Install stable version

Imports

SMTP
```
from aiosmtplib import SMTP
```
The main SMTP client class for direct control over the connection lifecycle.
send
```
from aiosmtplib import send
```
A high-level asynchronous function for sending email messages with minimal setup.

Quickstart

This quickstart demonstrates sending an email using the high-level `aiosmtplib.send` coroutine. It uses environment variables for configuration and handles common TLS/STARTTLS scenarios. For more complex interactions or persistent connections, the `SMTP` client class with an `async with` context manager is recommended.

import asyncio
import os
from email.message import EmailMessage
from aiosmtplib import send

async def main():
    sender_email = os.environ.get('SMTP_SENDER_EMAIL', 'sender@example.com')
    recipient_email = os.environ.get('SMTP_RECIPIENT_EMAIL', 'recipient@example.com')
    smtp_host = os.environ.get('SMTP_HOST', 'localhost')
    smtp_port = int(os.environ.get('SMTP_PORT', 25))
    smtp_password = os.environ.get('SMTP_PASSWORD', None)

    message = EmailMessage()
    message['From'] = sender_email
    message['To'] = recipient_email
    message['Subject'] = 'Hello from aiosmtplib!'
    message.set_content('This is a test email sent using aiosmtplib.')

    try:
        await send(
            message,
            hostname=smtp_host,
            port=smtp_port,
            username=sender_email if smtp_password else None,
            password=smtp_password,
            start_tls=True if smtp_port == 587 else False, # Use STARTTLS for common submission port
            use_tls=True if smtp_port == 465 else False # Use direct TLS for common SMTPS port
        )
        print(f"Email sent successfully from {sender_email} to {recipient_email}")
    except Exception as e:
        print(f"Failed to send email: {e}")

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →