aiosmtpd - Asyncio-based SMTP Server

Warnings

• breaking The signature of the `handle_NOOP()` method in custom handlers changed from taking zero arguments to requiring a single argument in version 1.4.x. Custom handlers implementing this method must be updated.
  Fix: Update `handle_NOOP(self, server)` to accept the `server` argument: `async def handle_NOOP(self, server): ...`
• gotcha By default, the SMTP AUTH extension might not be advertised or supported by the server unless a STARTTLS command is issued first, or `auth_require_tls=False` is explicitly passed to the `Controller` or `SMTP` constructor. This can cause authentication failures with clients expecting immediate AUTH support.
  Fix: If clients connect without STARTTLS and require AUTH, initialize `Controller` or `SMTP` with `auth_require_tls=False`: `Controller(handler, ..., auth_require_tls=False)`.
• deprecated The `process_message()` method in handler classes was deprecated. Implementations should now use the asynchronous `handle_DATA(self, server, session, envelope)` method for processing incoming mail data.
  Fix: Migrate `process_message()` logic to `async def handle_DATA(self, server, session, envelope): ...` ensuring it returns an SMTP response string (e.g., `'250 OK'`).
• deprecated The `authentication_handler` parameter for the `SMTP` class constructor was deprecated in favor of `authenticator` and is scheduled for removal in version 2.0.
  Fix: Replace `authentication_handler=my_func` with `authenticator=Authenticator(my_func)` (where `Authenticator` is imported from `aiosmtpd.smtp`).
• gotcha The default `ready_timeout` for `Controller.start()` to wait for the SMTP server thread to become ready changed from 1 second to 5 seconds. This could impact testing setups or deployments sensitive to startup times.
  Fix: Adjust tests or application logic that rely on a specific short startup timeout, or explicitly set `ready_timeout` in the `Controller` constructor: `Controller(handler, ..., ready_timeout=1.0)`.
• breaking While PyPI states `requires_python >=3.8`, the official documentation recommends CPython>=3.9 and PyPy>=3.9. The upcoming version 1.4.7 explicitly drops support for Python 3.8, requiring an upgrade if using newer `aiosmtpd` versions.
  Fix: Ensure your environment uses Python 3.9 or newer to guarantee compatibility with current and future `aiosmtpd` releases.

Install

• pip install aiosmtpd Install latest version

Imports

• Controller

  from aiosmtpd.controller import Controller

  The Controller class is in the 'controller' submodule.
• SMTP

  from aiosmtpd.smtp import SMTP

  Directly using SMTP is possible but Controller is often preferred for managing the server in a separate thread.
• handlers.Sink

  from aiosmtpd.handlers import Sink

  Commonly used handler for testing, discards all incoming mail.
• handlers.Debugging

  from aiosmtpd.handlers import Debugging

  Default handler for the command-line script; prints incoming mail to stdout.

Quickstart

This quickstart sets up a basic SMTP server on `127.0.0.1:8025` using the `Debugging` handler, which prints all received emails to the console. It leverages `Controller` to run the server in a separate thread, allowing the main program to continue running or wait for interruption. You can connect to this server with any SMTP client (e.g., `smtplib` or `telnet`).

import asyncio
from aiosmtpd.controller import Controller
from aiosmtpd.handlers import Debugging
import os

async def amain():
    # Use Debugging handler to print incoming emails to console
    handler = Debugging()
    
    # The Controller runs the SMTP server in a separate thread.
    # For testing/quickstart, localhost:8025 is common.
    controller = Controller(handler, hostname=os.environ.get('SMTP_HOST', '127.0.0.1'), port=int(os.environ.get('SMTP_PORT', 8025)))
    
    print(f"Starting SMTP server on {controller.hostname}:{controller.port}...")
    controller.start()
    print("SMTP server started. Press Ctrl+C to stop.")
    
    try:
        # Keep the main loop running while the controller's thread handles the SMTP server
        await asyncio.Event().wait()
    except asyncio.CancelledError:
        pass
    finally:
        controller.stop()
        print("SMTP server stopped.")

if __name__ == '__main__':
    # Run the asyncio event loop
    try:
        asyncio.run(amain())
    except KeyboardInterrupt:
        print("Server interrupted by user.")