| :mod:`smtpd` --- SMTP Server |
| ============================ |
| |
| .. module:: smtpd |
| :synopsis: A SMTP server implementation in Python. |
| |
| .. moduleauthor:: Barry Warsaw <barry@python.org> |
| .. sectionauthor:: Moshe Zadka <moshez@moshez.org> |
| |
| **Source code:** :source:`Lib/smtpd.py` |
| |
| -------------- |
| |
| This module offers several classes to implement SMTP (email) servers. |
| |
| Several server implementations are present; one is a generic |
| do-nothing implementation, which can be overridden, while the other two offer |
| specific mail-sending strategies. |
| |
| Additionally the SMTPChannel may be extended to implement very specific |
| interaction behaviour with SMTP clients. |
| |
| The code supports :RFC:`5321`, plus the :rfc:`1870` SIZE and :rfc:`6531` |
| SMTPUTF8 extensions. |
| |
| |
| SMTPServer Objects |
| ------------------ |
| |
| |
| .. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\ |
| map=None, enable_SMTPUTF8=False, decode_data=True) |
| |
| Create a new :class:`SMTPServer` object, which binds to local address |
| *localaddr*. It will treat *remoteaddr* as an upstream SMTP relayer. It |
| inherits from :class:`asyncore.dispatcher`, and so will insert itself into |
| :mod:`asyncore`'s event loop on instantiation. |
| |
| *data_size_limit* specifies the maximum number of bytes that will be |
| accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no |
| limit. |
| |
| *enable_SMTPUTF8* determins whether the ``SMTPUTF8`` extension (as defined |
| in :RFC:`6531`) should be enabled. The default is ``False``. If |
| *enable_SMTPUTF* is set to ``True``, the :meth:`process_smtputf8_message` |
| method must be defined. A :exc:`ValueError` is raised if both |
| *enable_SMTPUTF8* and *decode_data* are set to ``True`` at the same time. |
| |
| A dictionary can be specified in *map* to avoid using a global socket map. |
| |
| *decode_data* specifies whether the data portion of the SMTP transaction |
| should be decoded using UTF-8. The default is ``True`` for backward |
| compatibility reasons, but will change to ``False`` in Python 3.6. Specify |
| the keyword value explicitly to avoid the :exc:`DeprecationWarning`. |
| |
| .. method:: process_message(peer, mailfrom, rcpttos, data) |
| |
| Raise a :exc:`NotImplementedError` exception. Override this in subclasses to |
| do something useful with this message. Whatever was passed in the |
| constructor as *remoteaddr* will be available as the :attr:`_remoteaddr` |
| attribute. *peer* is the remote host's address, *mailfrom* is the envelope |
| originator, *rcpttos* are the envelope recipients and *data* is a string |
| containing the contents of the e-mail (which should be in :rfc:`5321` |
| format). |
| |
| If the *decode_data* constructor keyword is set to ``True``, the *data* |
| argument will be a unicode string. If it is set to ``False``, it |
| will be a bytes object. |
| |
| Return ``None`` to request a normal ``250 Ok`` response; otherwise |
| return the desired response string in :RFC:`5321` format. |
| |
| .. method:: process_smtputf8_message(peer, mailfrom, rcpttos, data) |
| |
| Raise a :exc:`NotImplementedError` exception. Override this in |
| subclasses to do something useful with messages when *enable_SMTPUTF8* |
| has been set to ``True`` and the SMTP client requested ``SMTPUTF8``, |
| since this method is called rather than :meth:`process_message` when the |
| client actively requests ``SMTPUTF8``. The *data* argument will always |
| be a bytes object, and any non-``None`` return value should conform to |
| :rfc:`6531`; otherwise, the API is the same as for |
| :meth:`process_message`. |
| |
| .. attribute:: channel_class |
| |
| Override this in subclasses to use a custom :class:`SMTPChannel` for |
| managing SMTP clients. |
| |
| .. versionchanged:: 3.4 |
| The *map* argument was added. |
| |
| .. versionchanged:: 3.5 |
| *localaddr* and *remoteaddr* may now contain IPv6 addresses. |
| |
| .. versionadded:: 3.5 |
| the *decode_data* and *enable_SMTPUTF8* constructor arguments, and the |
| :meth:`process_smtputf8_message` method. |
| |
| |
| DebuggingServer Objects |
| ----------------------- |
| |
| |
| .. class:: DebuggingServer(localaddr, remoteaddr) |
| |
| Create a new debugging server. Arguments are as per :class:`SMTPServer`. |
| Messages will be discarded, and printed on stdout. |
| |
| |
| PureProxy Objects |
| ----------------- |
| |
| |
| .. class:: PureProxy(localaddr, remoteaddr) |
| |
| Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. |
| Everything will be relayed to *remoteaddr*. Note that running this has a good |
| chance to make you into an open relay, so please be careful. |
| |
| |
| MailmanProxy Objects |
| -------------------- |
| |
| |
| .. class:: MailmanProxy(localaddr, remoteaddr) |
| |
| Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. |
| Everything will be relayed to *remoteaddr*, unless local mailman configurations |
| knows about an address, in which case it will be handled via mailman. Note that |
| running this has a good chance to make you into an open relay, so please be |
| careful. |
| |
| SMTPChannel Objects |
| ------------------- |
| |
| .. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,\ |
| map=None, enable_SMTPUTF8=False, decode_data=True) |
| |
| Create a new :class:`SMTPChannel` object which manages the communication |
| between the server and a single SMTP client. |
| |
| *conn* and *addr* are as per the instance variables described below. |
| |
| *data_size_limit* specifies the maximum number of bytes that will be |
| accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no |
| limit. |
| |
| *enable_SMTPUTF8* determins whether the ``SMTPUTF8`` extension (as defined |
| in :RFC:`6531`) should be enabled. The default is ``False``. A |
| :exc:`ValueError` is raised if both *enable_SMTPUTF8* and *decode_data* are |
| set to ``True`` at the same time. |
| |
| A dictionary can be specified in *map* to avoid using a global socket map. |
| |
| *decode_data* specifies whether the data portion of the SMTP transaction |
| should be decoded using UTF-8. The default is ``True`` for backward |
| compatibility reasons, but will change to ``False`` in Python 3.6. Specify |
| the keyword value explicitly to avoid the :exc:`DeprecationWarning`. |
| |
| To use a custom SMTPChannel implementation you need to override the |
| :attr:`SMTPServer.channel_class` of your :class:`SMTPServer`. |
| |
| .. versionchanged:: 3.5 |
| the *decode_data* and *enable_SMTPUTF8* arguments were added. |
| |
| The :class:`SMTPChannel` has the following instance variables: |
| |
| .. attribute:: smtp_server |
| |
| Holds the :class:`SMTPServer` that spawned this channel. |
| |
| .. attribute:: conn |
| |
| Holds the socket object connecting to the client. |
| |
| .. attribute:: addr |
| |
| Holds the address of the client, the second value returned by |
| :func:`socket.accept <socket.socket.accept>` |
| |
| .. attribute:: received_lines |
| |
| Holds a list of the line strings (decoded using UTF-8) received from |
| the client. The lines have their ``"\r\n"`` line ending translated to |
| ``"\n"``. |
| |
| .. attribute:: smtp_state |
| |
| Holds the current state of the channel. This will be either |
| :attr:`COMMAND` initially and then :attr:`DATA` after the client sends |
| a "DATA" line. |
| |
| .. attribute:: seen_greeting |
| |
| Holds a string containing the greeting sent by the client in its "HELO". |
| |
| .. attribute:: mailfrom |
| |
| Holds a string containing the address identified in the "MAIL FROM:" line |
| from the client. |
| |
| .. attribute:: rcpttos |
| |
| Holds a list of strings containing the addresses identified in the |
| "RCPT TO:" lines from the client. |
| |
| .. attribute:: received_data |
| |
| Holds a string containing all of the data sent by the client during the |
| DATA state, up to but not including the terminating ``"\r\n.\r\n"``. |
| |
| .. attribute:: fqdn |
| |
| Holds the fully-qualified domain name of the server as returned by |
| :func:`socket.getfqdn`. |
| |
| .. attribute:: peer |
| |
| Holds the name of the client peer as returned by ``conn.getpeername()`` |
| where ``conn`` is :attr:`conn`. |
| |
| The :class:`SMTPChannel` operates by invoking methods named ``smtp_<command>`` |
| upon reception of a command line from the client. Built into the base |
| :class:`SMTPChannel` class are methods for handling the following commands |
| (and responding to them appropriately): |
| |
| ======== =================================================================== |
| Command Action taken |
| ======== =================================================================== |
| HELO Accepts the greeting from the client and stores it in |
| :attr:`seen_greeting`. Sets server to base command mode. |
| EHLO Accepts the greeting from the client and stores it in |
| :attr:`seen_greeting`. Sets server to extended command mode. |
| NOOP Takes no action. |
| QUIT Closes the connection cleanly. |
| MAIL Accepts the "MAIL FROM:" syntax and stores the supplied address as |
| :attr:`mailfrom`. In extended command mode, accepts the |
| :rfc:`1870` SIZE attribute and responds appropriately based on the |
| value of *data_size_limit*. |
| RCPT Accepts the "RCPT TO:" syntax and stores the supplied addresses in |
| the :attr:`rcpttos` list. |
| RSET Resets the :attr:`mailfrom`, :attr:`rcpttos`, and |
| :attr:`received_data`, but not the greeting. |
| DATA Sets the internal state to :attr:`DATA` and stores remaining lines |
| from the client in :attr:`received_data` until the terminator |
| ``"\r\n.\r\n"`` is received. |
| HELP Returns minimal information on command syntax |
| VRFY Returns code 252 (the server doesn't know if the address is valid) |
| EXPN Reports that the command is not implemented. |
| ======== =================================================================== |