The SMTP class¶
At the heart of this module is the
SMTP class. This class implements the
RFC 5321 Simple Mail Transport
Protocol. Often you won’t run an
SMTP instance directly, but instead will
use a controller instance to run the server in a subthread.
>>> from aiosmtpd.controller import Controller
SMTP class is itself a subclass of StreamReaderProtocol.
While behavior for common SMTP commands can be specified using handlers, more complex specializations such as adding custom SMTP commands
require subclassing the
For example, let’s say you wanted to add a new SMTP command called
All methods implementing
SMTP commands are prefixed with
must also be coroutines. Here’s how you could implement this use case:
>>> import asyncio >>> from aiosmtpd.smtp import SMTP as Server, syntax >>> class MyServer(Server): ... @syntax('PING [ignored]') ... async def smtp_PING(self, arg): ... await self.push('259 Pong')
Now let’s run this server in a controller:
>>> from aiosmtpd.handlers import Sink >>> class MyController(Controller): ... def factory(self): ... return MyServer(self.handler) >>> controller = MyController(Sink()) >>> controller.start()
We can now connect to this server with an
>>> from smtplib import SMTP as Client >>> client = Client(controller.hostname, controller.port)
Let’s ping the server. Since the
PING command isn’t an official
command, we have to use the lower level interface to talk to it.
>>> code, message = client.docmd('PING') >>> code 259 >>> message b'Pong'
Because we prefixed the
smtp_PING() method with the
decorator, the command shows up in the
>>> print(client.help().decode('utf-8')) Supported commands: AUTH DATA EHLO HELO HELP MAIL NOOP PING QUIT RCPT RSET VRFY
And we can get more detailed help on the new command.
>>> print(client.help('PING').decode('utf-8')) Syntax: PING [ignored]
These methods are deprecated. See handler hooks instead.
SMTP server class also implements some hooks which your subclass can
override to provide additional responses.
- This hook makes it possible for subclasses to return additional
EHLOresponses. This method, called asynchronously and taking no arguments, can do whatever it wants, including (most commonly) pushing new
250-<command>responses to the client. This hook is called just before the standard
250 HELPwhich ends the
EHLOresponse from the server.
- This hook makes it possible to return additional
RSETresponses. This method, called asynchronously and taking no arguments, is called just before the standard
250 OKwhich ends the
RSETresponse from the server.
SMTP(handler, *, data_size_limit=33554432, enable_SMTPUTF8=False, decode_data=False, hostname=None, ident=None, tls_context=None, require_starttls=False, timeout=300, auth_required=False, auth_require_tls=True, auth_exclude_mechanism=None, auth_callback=None, loop=None)¶
handler is an instance of a handler class.
data_size_limit is the limit in number of bytes that is accepted for client SMTP commands. It is returned to ESMTP clients in the
250-SIZEresponse. The default is 33554432.
enable_SMTPUTF8 is a flag that when True causes the ESMTP
SMTPUTF8option to be returned to the client, and allows for UTF-8 content to be accepted. The default is False.
decode_data is a flag that when True, attempts to decode byte content in the
DATAcommand, assigning the string value to the envelope’s
contentattribute. The default is False.
hostname is the first part of the string returned in the
220greeting response given to clients when they first connect to the server. If not given, the system’s fully-qualified domain name is used.
ident is the second part of the string returned in the
220greeting response that identifies the software name and version of the SMTP server to the client. If not given, a default Python SMTP ident is used.
tls_context and require_starttls. The
STARTTLSoption of ESMTP (and LMTP), defined in RFC 3207, provides for secure connections to the server. For this option to be available, tls_context must be supplied, and require_starttls should be
True. See Enabling STARTTLS for a more in depth discussion on enabling
timeout is the number of seconds to wait between valid SMTP commands. After this time the connection will be closed by the server. The default is 300 seconds, as per RFC 2821.
auth_required specifies whether SMTP Authentication is mandatory or not for the session. This impacts some SMTP commands such as HELP, MAIL FROM, RCPT TO, and others.
auth_require_tls specifies whether
STARTTLSmust be used before AUTH exchange or not. If you set this to
Falsethen AUTH exchange can be done outside a TLS context, but the class will warn you of security considerations. Please note that require_starttls takes precedence over this setting.
auth_exclude_mechanism is an
Iterable[str]that specifies SMTP AUTH mechanisms to NOT use.
auth_callback is a function that accepts three arguments:
login: bytes, and
password: bytes. Based on these args, the function must return a
boolthat indicates whether the client’s authentication attempt is accepted/successful or not.
loop is the asyncio event loop to use. If not given,
asyncio.new_event_loop()is called to create the event loop.
The handler instance passed into the constructor.
The value of the data_size_limit argument passed into the constructor.
The value of the enable_SMTPUTF8 argument passed into the constructor.
220greeting hostname. This will either be the value of the hostname argument passed into the constructor, or the system’s fully qualified host name.
The value of the tls_context argument passed into the constructor.
True if both the tls_context argument to the constructor was given and the require_starttls flag was True.
The event loop being used. This will either be the given loop argument, or the new event loop that was created.
A flag that indicates whether authentication had succeeded.
A method subclasses can override to return custom
A method subclasses can override to return custom
The method that subclasses and handlers should use to return statuses to SMTP clients. This is a coroutine. status can be a bytes object, but for convenience it is more likely to be a string. If it’s a string, it must be ASCII, unless enable_SMTPUTF8 is True in which case it will be encoded as UTF-8.
Coroutine methods implementing the SMTP protocol commands. For example,
smtp_HELO()implements the SMTP
HELOcommand. Subclasses can override these, or add new command methods to implement custom extensions to the SMTP protocol. arg is the rest of the SMTP command given by the client, or None if nothing but the command was given.
context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)
The context must be initialized with a server certificate, private key, and/or
intermediate CA certificate chain with the
ssl.SSLContext.load_cert_chain() method. This can be done with
separate files, or an all in one file. Files must be in PEM format.
For example, if you wanted to use a self-signed certification for localhost,
which is easy to create but doesn’t provide much security, you could use the
openssl(1) command like so:
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'
and then in Python:
context = ssl.create_default_context(ssl.Purpose.CLIENT_AUTH) context.load_cert_chain('cert.pem', 'key.pem')
Now pass the
context object to the tls_context argument in the
Note that a number of exceptions can be generated by these methods, and by SSL connections, which you must be prepared to handle. Additional documentation is available in Python’s ssl module, and should be reviewed before use; in particular if client authentication and/or advanced error handling is desired.
If require_starttls is
True, a TLS session must be initiated for the
server to respond to any commands other than
If require_starttls is
False (the default), use of TLS is not required;
the client may upgrade the connection to TLS, or may use any supported
command over an insecure connection.
If tls_context is not supplied, the
STARTTLS option will not be
advertised, and the
STARTTLS command will not be accepted.
require_starttls is meaningless in this case, and should be set to