1 :mod:`smtpd` --- SMTP Server 2 ============================ 3 4 .. module:: smtpd 5 :synopsis: A SMTP server implementation in Python. 6 7 .. moduleauthor:: Barry Warsaw <barry (a] python.org> 8 .. sectionauthor:: Moshe Zadka <moshez (a] moshez.org> 9 10 **Source code:** :source:`Lib/smtpd.py` 11 12 -------------- 13 14 This module offers several classes to implement SMTP (email) servers. 15 16 .. seealso:: 17 18 The `aiosmtpd <http://aiosmtpd.readthedocs.io/>`_ package is a recommended 19 replacement for this module. It is based on :mod:`asyncio` and provides a 20 more straightforward API. :mod:`smtpd` should be considered deprecated. 21 22 Several server implementations are present; one is a generic 23 do-nothing implementation, which can be overridden, while the other two offer 24 specific mail-sending strategies. 25 26 Additionally the SMTPChannel may be extended to implement very specific 27 interaction behaviour with SMTP clients. 28 29 The code supports :RFC:`5321`, plus the :rfc:`1870` SIZE and :rfc:`6531` 30 SMTPUTF8 extensions. 31 32 33 SMTPServer Objects 34 ------------------ 35 36 37 .. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\ 38 map=None, enable_SMTPUTF8=False, decode_data=False) 39 40 Create a new :class:`SMTPServer` object, which binds to local address 41 *localaddr*. It will treat *remoteaddr* as an upstream SMTP relayer. Both 42 *localaddr* and *remoteaddr* should be a :ref:`(host, port) <host_port>` 43 tuple. The object inherits from :class:`asyncore.dispatcher`, and so will 44 insert itself into :mod:`asyncore`'s event loop on instantiation. 45 46 *data_size_limit* specifies the maximum number of bytes that will be 47 accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no 48 limit. 49 50 *map* is the socket map to use for connections (an initially empty 51 dictionary is a suitable value). If not specified the :mod:`asyncore` 52 global socket map is used. 53 54 *enable_SMTPUTF8* determines whether the ``SMTPUTF8`` extension (as defined 55 in :RFC:`6531`) should be enabled. The default is ``False``. 56 When ``True``, ``SMTPUTF8`` is accepted as a parameter to the ``MAIL`` 57 command and when present is passed to :meth:`process_message` in the 58 ``kwargs['mail_options']`` list. *decode_data* and *enable_SMTPUTF8* 59 cannot be set to ``True`` at the same time. 60 61 *decode_data* specifies whether the data portion of the SMTP transaction 62 should be decoded using UTF-8. When *decode_data* is ``False`` (the 63 default), the server advertises the ``8BITMIME`` 64 extension (:rfc:`6152`), accepts the ``BODY=8BITMIME`` parameter to 65 the ``MAIL`` command, and when present passes it to :meth:`process_message` 66 in the ``kwargs['mail_options']`` list. *decode_data* and *enable_SMTPUTF8* 67 cannot be set to ``True`` at the same time. 68 69 .. method:: process_message(peer, mailfrom, rcpttos, data, **kwargs) 70 71 Raise a :exc:`NotImplementedError` exception. Override this in subclasses to 72 do something useful with this message. Whatever was passed in the 73 constructor as *remoteaddr* will be available as the :attr:`_remoteaddr` 74 attribute. *peer* is the remote host's address, *mailfrom* is the envelope 75 originator, *rcpttos* are the envelope recipients and *data* is a string 76 containing the contents of the e-mail (which should be in :rfc:`5321` 77 format). 78 79 If the *decode_data* constructor keyword is set to ``True``, the *data* 80 argument will be a unicode string. If it is set to ``False``, it 81 will be a bytes object. 82 83 *kwargs* is a dictionary containing additional information. It is empty 84 if ``decode_data=True`` was given as an init argument, otherwise 85 it contains the following keys: 86 87 *mail_options*: 88 a list of all received parameters to the ``MAIL`` 89 command (the elements are uppercase strings; example: 90 ``['BODY=8BITMIME', 'SMTPUTF8']``). 91 92 *rcpt_options*: 93 same as *mail_options* but for the ``RCPT`` command. 94 Currently no ``RCPT TO`` options are supported, so for now 95 this will always be an empty list. 96 97 Implementations of ``process_message`` should use the ``**kwargs`` 98 signature to accept arbitrary keyword arguments, since future feature 99 enhancements may add keys to the kwargs dictionary. 100 101 Return ``None`` to request a normal ``250 Ok`` response; otherwise 102 return the desired response string in :RFC:`5321` format. 103 104 .. attribute:: channel_class 105 106 Override this in subclasses to use a custom :class:`SMTPChannel` for 107 managing SMTP clients. 108 109 .. versionadded:: 3.4 110 The *map* constructor argument. 111 112 .. versionchanged:: 3.5 113 *localaddr* and *remoteaddr* may now contain IPv6 addresses. 114 115 .. versionadded:: 3.5 116 The *decode_data* and *enable_SMTPUTF8* constructor parameters, and the 117 *kwargs* parameter to :meth:`process_message` when *decode_data* is 118 ``False``. 119 120 .. versionchanged:: 3.6 121 *decode_data* is now ``False`` by default. 122 123 124 DebuggingServer Objects 125 ----------------------- 126 127 128 .. class:: DebuggingServer(localaddr, remoteaddr) 129 130 Create a new debugging server. Arguments are as per :class:`SMTPServer`. 131 Messages will be discarded, and printed on stdout. 132 133 134 PureProxy Objects 135 ----------------- 136 137 138 .. class:: PureProxy(localaddr, remoteaddr) 139 140 Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. 141 Everything will be relayed to *remoteaddr*. Note that running this has a good 142 chance to make you into an open relay, so please be careful. 143 144 145 MailmanProxy Objects 146 -------------------- 147 148 149 .. class:: MailmanProxy(localaddr, remoteaddr) 150 151 Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. 152 Everything will be relayed to *remoteaddr*, unless local mailman configurations 153 knows about an address, in which case it will be handled via mailman. Note that 154 running this has a good chance to make you into an open relay, so please be 155 careful. 156 157 SMTPChannel Objects 158 ------------------- 159 160 .. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,\ 161 map=None, enable_SMTPUTF8=False, decode_data=False) 162 163 Create a new :class:`SMTPChannel` object which manages the communication 164 between the server and a single SMTP client. 165 166 *conn* and *addr* are as per the instance variables described below. 167 168 *data_size_limit* specifies the maximum number of bytes that will be 169 accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no 170 limit. 171 172 *enable_SMTPUTF8* determines whether the ``SMTPUTF8`` extension (as defined 173 in :RFC:`6531`) should be enabled. The default is ``False``. 174 *decode_data* and *enable_SMTPUTF8* cannot be set to ``True`` at the same 175 time. 176 177 A dictionary can be specified in *map* to avoid using a global socket map. 178 179 *decode_data* specifies whether the data portion of the SMTP transaction 180 should be decoded using UTF-8. The default is ``False``. 181 *decode_data* and *enable_SMTPUTF8* cannot be set to ``True`` at the same 182 time. 183 184 To use a custom SMTPChannel implementation you need to override the 185 :attr:`SMTPServer.channel_class` of your :class:`SMTPServer`. 186 187 .. versionchanged:: 3.5 188 The *decode_data* and *enable_SMTPUTF8* parameters were added. 189 190 .. versionchanged:: 3.6 191 *decode_data* is now ``False`` by default. 192 193 The :class:`SMTPChannel` has the following instance variables: 194 195 .. attribute:: smtp_server 196 197 Holds the :class:`SMTPServer` that spawned this channel. 198 199 .. attribute:: conn 200 201 Holds the socket object connecting to the client. 202 203 .. attribute:: addr 204 205 Holds the address of the client, the second value returned by 206 :func:`socket.accept <socket.socket.accept>` 207 208 .. attribute:: received_lines 209 210 Holds a list of the line strings (decoded using UTF-8) received from 211 the client. The lines have their ``"\r\n"`` line ending translated to 212 ``"\n"``. 213 214 .. attribute:: smtp_state 215 216 Holds the current state of the channel. This will be either 217 :attr:`COMMAND` initially and then :attr:`DATA` after the client sends 218 a "DATA" line. 219 220 .. attribute:: seen_greeting 221 222 Holds a string containing the greeting sent by the client in its "HELO". 223 224 .. attribute:: mailfrom 225 226 Holds a string containing the address identified in the "MAIL FROM:" line 227 from the client. 228 229 .. attribute:: rcpttos 230 231 Holds a list of strings containing the addresses identified in the 232 "RCPT TO:" lines from the client. 233 234 .. attribute:: received_data 235 236 Holds a string containing all of the data sent by the client during the 237 DATA state, up to but not including the terminating ``"\r\n.\r\n"``. 238 239 .. attribute:: fqdn 240 241 Holds the fully-qualified domain name of the server as returned by 242 :func:`socket.getfqdn`. 243 244 .. attribute:: peer 245 246 Holds the name of the client peer as returned by ``conn.getpeername()`` 247 where ``conn`` is :attr:`conn`. 248 249 The :class:`SMTPChannel` operates by invoking methods named ``smtp_<command>`` 250 upon reception of a command line from the client. Built into the base 251 :class:`SMTPChannel` class are methods for handling the following commands 252 (and responding to them appropriately): 253 254 ======== =================================================================== 255 Command Action taken 256 ======== =================================================================== 257 HELO Accepts the greeting from the client and stores it in 258 :attr:`seen_greeting`. Sets server to base command mode. 259 EHLO Accepts the greeting from the client and stores it in 260 :attr:`seen_greeting`. Sets server to extended command mode. 261 NOOP Takes no action. 262 QUIT Closes the connection cleanly. 263 MAIL Accepts the "MAIL FROM:" syntax and stores the supplied address as 264 :attr:`mailfrom`. In extended command mode, accepts the 265 :rfc:`1870` SIZE attribute and responds appropriately based on the 266 value of *data_size_limit*. 267 RCPT Accepts the "RCPT TO:" syntax and stores the supplied addresses in 268 the :attr:`rcpttos` list. 269 RSET Resets the :attr:`mailfrom`, :attr:`rcpttos`, and 270 :attr:`received_data`, but not the greeting. 271 DATA Sets the internal state to :attr:`DATA` and stores remaining lines 272 from the client in :attr:`received_data` until the terminator 273 ``"\r\n.\r\n"`` is received. 274 HELP Returns minimal information on command syntax 275 VRFY Returns code 252 (the server doesn't know if the address is valid) 276 EXPN Reports that the command is not implemented. 277 ======== =================================================================== 278
