aiosmtplib Documentation

SMTP is a sequential protocol; commands must be sent in a specific order. Because of this, using asyncio.gather to run multiple SMTP.send_message tasks in parallel on a single client is not more efficient than running them in sequence, as the client must wait for one mail to finish before starting the next.

Best Practice: If you need to send a large volume of emails, create multiple SMTP instances (multiple connections) and distribute the workload across them.

Because OAuth2 access tokens are typically short-lived (e.g., 1 hour), your oauth_token_generator must be responsible for managing token lifecycle.

aiosmtplib does not track token expiry or automatically retry on authentication failure.

Your generator function must:

1. Check if the current token is expired.
2. Refresh the token if necessary.
3. Return a valid, non-expired token.

If you are using synchronous libraries like google-auth to handle refreshes, you should run the refresh logic in a separate thread using asyncio.to_thread to avoid blocking the event loop.

aiosmtplib supports three primary connection encryption modes. Choosing the correct one depends on the port and the security requirements of your SMTP server:

1. Plaintext: The connection is entirely unencrypted. Typically uses port 25. Note that most authentication methods are unsupported on unencrypted connections. This is best for local servers or testing.
2. TLS/SSL: The TLS handshake occurs immediately upon connection establishment, ensuring all traffic is encrypted from the start. Typically uses port 465. This is the recommended method where available.
3. STARTTLS: An initial unencrypted connection is established, and the connection is upgraded to an encrypted state via the STARTTLS command after the initial greeting. Typically uses port 587. Most servers require this upgrade before allowing authentication (AUTH) commands.

To send an email asynchronously, use the aiosmtplib.send() function. You can pass an EmailMessage object (from the standard email.message module) along with the hostname and port of your SMTP server. This function must be awaited within an asyncio event loop.

import asyncio
from email.message import EmailMessage

import aiosmtplib

message = EmailMessage()
message["From"] = "root@localhost"
message["To"] = "somebody@example.com"
message["Subject"] = "Hello World!"
message.set_content("Sent via aiosmtplib")

asyncio.run(aiosmtplib.send(message, hostname="127.0.0.1", port=25))

By default, aiosmtplib will automatically upgrade the connection using STARTTLS if the server advertises support.

Important: Setting use_tls=True on a STARTTLS server will typically result in a connection error.

To opt out of automatic STARTTLS during the initial connection, set start_tls=False. You can then manually call SMTP.starttls() if required.

smtp_client = aiosmtplib.SMTP(
    hostname="smtp.gmail.com",
    port=587,
    start_tls=False,
    use_tls=False,
)
await smtp_client.connect()
await smtp_client.starttls()

To use aiosmtplib, ensure your environment meets the following requirement:

• Python 3.10+

Direct TLS/SSL

If the SMTP server supports direct connection via TLS/SSL (e.g., on port 465), pass use_tls=True to the send() function.

STARTTLS

By default, aiosmtplib will automatically upgrade the connection using STARTTLS if the server advertises support.

• To opt out of automatic STARTTLS on connect, pass start_tls=False.
• Note: Setting use_tls=True on a server that expects STARTTLS will typically result in a connection error.

# Direct TLS/SSL
await send(message, hostname="smtp.gmail.com", port=465, use_tls=True)

# Opting out of STARTTLS
await send(message, hostname="smtp.gmail.com", port=587, start_tls=False)

To authenticate with an SMTP server using standard credentials, pass the username and password keyword arguments to the send() coroutine.

await send(
    message,
    hostname="smtp.gmail.com",
    port=587,
    username="test@gmail.com",
    password="test"
)

The aiosmtplib.send() coroutine is the recommended entry point for most email sending use cases. To use it, create an email.message.EmailMessage object, set the required headers (at minimum From and one of To, Cc, or Bcc), and pass it to send() along with the SMTP server's hostname and port.

import asyncio
from email.message import EmailMessage
import aiosmtplib

async def send_hello_world():
    message = EmailMessage()
    message["From"] = "root@localhost"
    message["To"] = "somebody@example.com"
    message["Subject"] = "Hello World!"
    message.set_content("Sent via aiosmtplib")

    await aiosmtplib.send(message, hostname="127.0.0.1", port=1025)

asyncio.run(send_hello_world())