aiosmtplib

library5.1.2pypypi✓ verified 25d ago

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.

communication http-networking

pip install aiosmtplib

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · AIOSMTPLIB

aiosmtplib

communicationpythonv5.1.2

Install

1.6s avg

Import

335ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v5.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.356s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.314s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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())

Debug

Known issues

breakingPython 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).

affects: 5.0.0+

breakingIn 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.

affects: 3.0.0+

gotchaWhen 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`.

affects: All versions

gotchaSMTP 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.

affects: All versions

gotchaWhen attempting to connect or send emails, ensure that the target SMTP server is running and accessible from the client's environment. Common network errors like 'Connection refused' (Errno 111) indicate that aiosmtplib could not establish a TCP connection, often due to the server being down, incorrect host/port, or firewall restrictions.

fix

Verify the SMTP server's status and network accessibility. Check the provided host and port, and ensure no firewalls are blocking the connection. If testing locally, make sure a local SMTP server (e.g., Postfix, SMTPServer from Python's smtpd) is active and listening on the specified port.

affects: All versions

gotchaConnection attempts failed with `Errno 111` (Connection refused). This typically means no SMTP server is running or listening on the specified host and port, or a firewall is blocking the connection. `aiosmtplib` requires a running SMTP server to connect to.

fix

Ensure an SMTP server is running and accessible on the specified host and port (e.g., localhost:25). Verify network connectivity and firewall rules if connecting remotely or within isolated environments like containers.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'aiosmtplib'

The 'aiosmtplib' package is not installed in the Python environment.

fix

Install the package using pip: 'pip install aiosmtplib'.

AttributeError: 'SMTP' object has no attribute 'sendmail'

Attempting to use the 'sendmail' method on an 'SMTP' object that hasn't been properly initialized or connected.

fix

Ensure the 'SMTP' object is correctly initialized and connected before calling 'sendmail'.

AttributeError: 'NoneType' object has no attribute 'strip'

Accessing an attribute on a 'NoneType' object, possibly due to a misspelled or missing header in the email message.

fix

Verify that all required headers (e.g., 'From', 'To') are correctly set in the email message.

aiosmtplib.errors.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted')

The SMTP server rejected the provided username or password, often due to incorrect credentials, two-factor authentication requiring an app-specific password, or the need to enable 'less secure app access' (for older systems).

fix

Verify your username and password. If using a service like Gmail, generate an 'App Password' for your application and use that instead of your primary account password, and ensure two-factor authentication is enabled if required for app passwords.

aiosmtplib.errors.SMTPServerDisconnected: Connection lost

The connection to the SMTP server was unexpectedly closed or lost, which can be due to network issues, server-side errors, timeouts, or attempting a command without an active connection.

fix

Ensure the SMTP server address and port are correct, check network connectivity, confirm the server is running, and handle potential timeouts by setting appropriate `timeout` values for `connect()` and other operations. Ensure you call `await smtp.connect()` before other commands.

Upgrade

Version history

5.1.2latest on PyPI · released Jun 20, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

66 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cole/aiosmtplib ↗

packagehttps://pypi.org/project/aiosmtplib/ ↗

docshttps://aiosmtplib.readthedocs.io/en/stable/ ↗

changeloghttps://github.com/cole/aiosmtplib/blob/main/CHANGELOG.rst ↗