Handlers

Handlers are classes which can implement hook methods that get called at various points in the SMTP dialog.

Handlers can also be named on the command line, but if the class’s constructor takes arguments, you must define a @classmethod that converts the positional arguments and returns a handler instance:

classmethod from_cli(cls, parser, *args)

Convert the positional arguments, as strings passed in on the command line, into a handler instance.

parser is the ArgumentParser instance in use.

If this method does not recognize the positional arguments passed in parser, it can optionally call parser.error with the error message.

If from_cli() is not defined, the handler can still be used on the command line, but its constructor cannot accept arguments.

Handler Hooks

Handlers can implement hooks that get called during the SMTP dialog, or in exceptional cases. These handler hooks are ALL called asynchronously (i.e. they are coroutines).

All handler hooks are optional and default behaviors are carried out by the SMTP class when a hook is omitted, so you only need to implement the ones you care about.

When a handler hook is defined, it may have additional responsibilities as described below.

Common Arguments

All handler hooks will be called with at least three arguments:

server: SMTP: The SMTP server instance

session: Session: The session instance currently being handled, and

envelope: Envelope: The envelope instance of the current SMTP Transaction

Some handler hooks will receive additional arguments.

Supported Hooks

The following hooks are currently supported (in alphabetical order):

handle_AUTH(server, session, envelope, args)

Called to handle AUTH command if you need custom AUTH behavior.

For more information, please read the documentation for Authentication System.

async handle_DATA(server, session, envelope) → str

Returns:: Response message to be sent to the client

Called during DATA after the entire message (“SMTP content” as described in RFC 5321) has been received.

The content is available in envelope.original_content as type bytes, normalized according to the transparency rules as defined in RFC 5321, §4.5.2.

In addition, the envelope.content attribute will also contain the contents; the type depends on whether SMTP was instantiated with decode_data=False or decode_data=True. See Envelope.content for more info.

async handle_EHLO(server, session, envelope, hostname, responses) → List[str]

Parameters:: hostname (str) – The host name given by the client in the EHLO command
Returns:: Response message to be sent to the client

This hook is called during EHLO.

This hook may push additional 250-<command> responses to the client by doing await server.push(status) before returning "250 HELP" as the final response.

Important

If the handler sets the session.host_name attribute to a false-y value (or leave it as the default None value) it will signal later steps that HELO failed and need to be performed again.

This also applies to the handle_EHLO() hook below.

Deprecated since version 1.3: Use the 5-argument form instead. Support for the 4-argument form will be removed in version 2.0

async handle_EHLO(server, session, envelope, hostname, responses) → List[str]

Parameters:

hostname (str) – The host name given by the client in the EHLO command
responses (List[str]) – The ‘planned’ responses to the EHLO command including the last 250 HELP response.

Returns:

List of response messages to be sent to the client

Called during EHLO.

The hook MUST return a list containing the desired responses. The returned list should end with 250 HELP

This hook MUST also set the :attr:session.host_name attribute.

Important

It is strongly recommended to not change element [0] of the list (containing the hostname of the SMTP server).

async handle_HELO(server, session, envelope, hostname) → str

Parameters:: hostname (str) – The host name given by client during HELO
Returns:: Response message to be sent to the client

This hook is called during HELO.

If implemented, this hook MUST also set the :attr:session.host_name attribute before returning '250 {}'.format(server.hostname) as the status.

async handle_MAIL(server, session, envelope, address, mail_options) → str

Parameters:

address (str) – The parsed email address given by the client in the MAIL FROM command
mail_options (List[str]) – Additional ESMTP MAIL options provided by the client

Returns:

Response message to be sent to the client

Called during MAIL FROM.

If implemented, this hook MUST also set the envelope.mail_from attribute and it MAY extend envelope.mail_options (which is always a Python list).

async handle_NOOP(server, session, envelope, arg) → str

Parameters:: arg (str) – All characters following the NOOP command
Returns:: Response message to be sent to the client

Called during NOOP.

handle_PROXY(server, session, envelope, proxy_data)

Parameters:

server (SMTP) – The SMTP instance invoking the hook.
session (Session) – The Session data so far (see Important note below)
envelope (Envelope) – The Envelope data so far (see Important note below)
proxy_data (ProxyData) – The result of parsing the PROXY Header

Returns:

Truthy or Falsey, indicating if the connection may continue or not, respectively

Called during PROXY Protocol Handshake.

See PROXY Protocol Support for more information.

async handle_QUIT(server, session, envelope) → str

Returns:: Response message to be sent to the client

Called during QUIT.

async handle_RCPT(server, session, envelope, address, rcpt_options) → str

Parameters:

address (str) – The parsed email address given by the client in the RCPT TO command
rcpt_options (List[str]) – Additional ESMTP RCPT options provided by the client

Returns:

Response message to be sent to the client

Called during RCPT TO.

If implemented, this hook SHOULD append the address to envelope.rcpt_tos and it MAY extend envelope.rcpt_options (both of which are always Python lists).

async handle_RSET(server, session, envelope) → str

Returns:: Response message to be sent to the client

Called during RSET.

async handle_VRFY(server, session, envelope, address) → str

Parameters:: address (str) – The parsed email address given by the client in the VRFY command
Returns:: Response message to be sent to the client

Called during VRFY.

In addition to the SMTP command hooks, the following hooks can also be implemented by handlers. These have different APIs, and are called synchronously (i.e. they are not coroutines).

handle_STARTTLS(server, session, envelope): If implemented, and if SSL is supported, this method gets called during the TLS handshake phase of connection_made(). It should return True if the handshake succeeded, and False otherwise.

handle_exception(error): If implemented, this method is called when any error occurs during the handling of a connection (e.g. if an smtp_<command>() method raises an exception). The exception object is passed in. This method must return a status string, such as '542 Internal server error'. If the method returns None or raises an exception, an exception will be logged, and a 451 code will be returned to the client.

Important

If client connection is lost, this handler will NOT be called.

Built-in handlers

The following built-in handlers can be imported from aiosmtpd.handlers:

class aiosmtpd.handlers.AsyncMessage

A subclass of the Message handler, it is also an abstract base class (it must be subclassed).

The only difference with Message is that handle_message() is called asynchronously.

This class cannot be used on the command line.

class aiosmtpd.handlers.Debugging

This class prints the contents of the received messages to a given output stream. Programmatically, you can pass the stream to print to into the constructor.

When specified on the command line, the (optional) positional argument must either be the string stdout or stderr indicating which stream to use. Examples:

aiosmtpd -c aiosmtpd.handlers.Debugging
aiosmtpd -c aiosmtpd.handlers.Debugging stderr
aiosmtpd -c aiosmtpd.handlers.Debugging stdout

class aiosmtpd.handlers.Mailbox

A subclass of the Message handler which adds the messages to a Maildir. See The Mailbox Handler for details.

When specified on the command line, it accepts exactly one positional argument which is the maildir (i.e, directory where email messages will be stored.) Example:

aiosmtpd -c aiosmtpd.handlers.Mailbox /home/myhome/Maildir

class aiosmtpd.handlers.Message

This class is an abstract base class (it must be subclassed) which converts the message content into a message instance. The class used to create these instances can be passed to the constructor, and defaults to email.message.Message

This message instance gains a few additional headers (e.g. X-Peer, X-MailFrom, and X-RcptTo). You can override this behavior by overriding the prepare_message() method, which takes a session and an envelope. The message instance is then passed to the handler’s handle_message() method. It is this method that must be implemented in the subclass.

prepare_message() and handle_message()`() are both called synchronously.

This class cannot be used on the command line.

class aiosmtpd.handlers.Proxy

This class is a relatively simple SMTP proxy; it forwards messages to a remote host and port. The constructor takes the host name and port as positional arguments.

This class cannot be used on the command line.

Important

Do not confuse this class with the PROXY Protocol; they are two totally different things.

class aiosmtpd.handlers.Sink

This class just consumes and discards messages. It’s essentially the “no op” handler.

It can be used on the command line, but accepts no positional arguments. Example:

aiosmtpd -c aiosmtpd.handlers.Sink

The Mailbox Handler

A convenient handler is the Mailbox handler, which stores incoming messages into a maildir.

To try it, let’s first prepare an ExitStack to automatically clean up after we finish:

>>> from contextlib import ExitStack
>>> from tempfile import TemporaryDirectory
>>> # Clean up the temporary directory at the end
>>> resources = ExitStack()
>>> tempdir = resources.enter_context(TemporaryDirectory())

Then, prepare the controller:

>>> import os
>>> from aiosmtpd.controller import Controller
>>> from aiosmtpd.handlers import Mailbox
>>> #
>>> maildir_path = os.path.join(tempdir, 'maildir')
>>> controller = Controller(Mailbox(maildir_path))
>>> controller.start()
>>> # Arrange for the controller to be stopped at the end
>>> ignore = resources.callback(controller.stop)

Now we can connect to the server and send it a message…

>>> from smtplib import SMTP
>>> client = SMTP(controller.hostname, controller.port)
>>> client.sendmail('aperson@example.com', ['bperson@example.com'], """\
... From: Anne Person <anne@example.com>
... To: Bart Person <bart@example.com>
... Subject: A test
... Message-ID: <ant>
...
... Hi Bart, this is Anne.
... """)
{}

…and a second message…

>>> client.sendmail('cperson@example.com', ['dperson@example.com'], """\
... From: Cate Person <cate@example.com>
... To: Dave Person <dave@example.com>
... Subject: A test
... Message-ID: <bee>
...
... Hi Dave, this is Cate.
... """)
{}

…and a third message.

>>> client.sendmail('eperson@example.com', ['fperson@example.com'], """\
... From: Elle Person <elle@example.com>
... To: Fred Person <fred@example.com>
... Subject: A test
... Message-ID: <cat>
...
... Hi Fred, this is Elle.
... """)
{}

We open up the mailbox again, and all three messages are waiting for us.

>>> from mailbox import Maildir
>>> from operator import itemgetter
>>> mailbox = Maildir(maildir_path)
>>> messages = sorted(mailbox, key=itemgetter('message-id'))
>>> for message in messages:
...     print(message['Message-ID'], message['From'], message['To'])
<ant> Anne Person <anne@example.com> Bart Person <bart@example.com>
<bee> Cate Person <cate@example.com> Dave Person <dave@example.com>
<cat> Elle Person <elle@example.com> Fred Person <fred@example.com>

Cleanup when we’re done.

>>> resources.close()