# 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:

`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 `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) and they must return a status string, such as `'250 OK'`. 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.

All handler hooks take at least three arguments, the `SMTP` server instance, a session instance, and an envelope instance. Some methods take additional arguments.

The following hooks are currently defined:

`handle_HELO(server, session, envelope, hostname)`
  Called during `HELO`. The `hostname` argument is the host name given by the client in the `HELO` command. If implemented, this hook must also set the `session.host_name` attribute before returning `'250 {}'.format(server.hostname)` as the status.
`handle_EHLO(server, session, envelope, hostname)`
  Called during `EHLO`. The `hostname` argument is the host name given by the client in the `EHLO` command. If implemented, this hook must also set the `session.host_name` attribute. This hook may push additional `250-<command>` responses to the client by yielding from `server.push(status)` before returning `250 HELP` as the final response.
`handle_NOOP(server, session, envelope, arg)`
  Called during `NOOP`.
`handle_QUIT(server, session, envelope)`
  Called during `QUIT`.
`handle_VRFY(server, session, envelope, address)`
  Called during `VRFY`. The `address` argument is the parsed email address given by the client in the `VRFY` command.
`handle_MAIL(server, session, envelope, address, mail_options)`
  Called during `MAIL FROM`. The `address` argument is the parsed email address given by the client in the `MAIL FROM` command, and `mail_options` are any additional ESMTP mail options providing by the client. 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).
`handle_RCPT(server, session, envelope, address, rcpt_options)`
  Called during `RCPT TO`. The `address` argument is the parsed email address given by the client in the `RCPT TO` command, and `rcpt_options` are any additional ESMTP recipient options providing by the client. If implemented, this hook should append the address to `envelope.rcpt_tos` and may extend `envelope.rcpt_options` (both of which are always Python lists).
`handle_RSET(server, session, envelope)`
  Called during `RSET`.
`handle_DATA(server, session, envelope)`
  Called during `DATA` after the entire message (“SMTP content” as described in RFC 5321) has been received. The content is available on the `envelope` object, but the values are dependent on whether the `SMTP` class was instantiated with `decode_data=False` (the default) or `decode_data=True`. In the former case, both `envelope.content` and `envelope.original_content` will be the content bytes (normalized according to the transparency rules in RFC 5321, §4.5.2). In the latter case, `envelope.original_content` will be the normalized bytes, but `envelope.content` will be the UTF-8 decoded string of the original content.

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 500 code will be returned to the client.

## Built-in handlers

The following built-in handlers can be imported from `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 positional argument must either be the string `stdout` or `stderr` indicating which stream to use.

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

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

- `Message` - this class is a 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 handler cannot be used on the command line.

- `AsyncMessage` - a subclass of the `Message` handler, with the only difference being that `handle_message()` is called asynchronously. This handler cannot be used on the command line.

- `Mailbox` - a subclass of the `Message` handler which adds the messages to a Maildir. See below for details.

## The Mailbox handler

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

    >>> import os
    >>> from aiosmtpd.controller import Controller
    >>> from aiosmtpd.handlers import Mailbox
    >>> from tempfile import TemporaryDirectory
    >>> # Clean up the temporary directory at the end of this doctest.
    >>> tempdir = resources.enter_context(TemporaryDirectory())

    >>> maildir_path = os.path.join(tempdir, 'maildir')
    >>> controller = Controller(Mailbox(maildir_path))
    >>> controller.start()
    >>> # Arrange for the controller to be stopped at the end of this doctest.
    >>> 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>