{"library":"aiosmtplib","title":"Asyncio SMTP Client","description":"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.","status":"active","version":"5.1.0","language":"en","source_language":"en","source_url":"https://github.com/cole/aiosmtplib","tags":["asyncio","email","smtp","client","networking"],"install":[{"cmd":"pip install aiosmtplib","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The main SMTP client class for direct control over the connection lifecycle.","symbol":"SMTP","correct":"from aiosmtplib import SMTP"},{"note":"A high-level asynchronous function for sending email messages with minimal setup.","symbol":"send","correct":"from aiosmtplib import send"}],"quickstart":{"code":"import asyncio\nimport os\nfrom email.message import EmailMessage\nfrom aiosmtplib import send\n\nasync def main():\n    sender_email = os.environ.get('SMTP_SENDER_EMAIL', 'sender@example.com')\n    recipient_email = os.environ.get('SMTP_RECIPIENT_EMAIL', 'recipient@example.com')\n    smtp_host = os.environ.get('SMTP_HOST', 'localhost')\n    smtp_port = int(os.environ.get('SMTP_PORT', 25))\n    smtp_password = os.environ.get('SMTP_PASSWORD', None)\n\n    message = EmailMessage()\n    message['From'] = sender_email\n    message['To'] = recipient_email\n    message['Subject'] = 'Hello from aiosmtplib!'\n    message.set_content('This is a test email sent using aiosmtplib.')\n\n    try:\n        await send(\n            message,\n            hostname=smtp_host,\n            port=smtp_port,\n            username=sender_email if smtp_password else None,\n            password=smtp_password,\n            start_tls=True if smtp_port == 587 else False, # Use STARTTLS for common submission port\n            use_tls=True if smtp_port == 465 else False # Use direct TLS for common SMTPS port\n        )\n        print(f\"Email sent successfully from {sender_email} to {recipient_email}\")\n    except Exception as e:\n        print(f\"Failed to send email: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":"5.0.0+"},{"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.","message":"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.","severity":"breaking","affected_versions":"3.0.0+"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T19:43:13.997Z","next_check":"2026-07-05T00:00:00.000Z"}