1:mod:`smtpd` --- SMTP Server
2============================
3
4.. module:: smtpd
5   :synopsis: A SMTP server implementation in Python.
6
7.. moduleauthor:: Barry Warsaw <barry@python.org>
8.. sectionauthor:: Moshe Zadka <moshez@moshez.org>
9
10**Source code:** :source:`Lib/smtpd.py`
11
12--------------
13
14This 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
22Several server implementations are present; one is a generic
23do-nothing implementation, which can be overridden, while the other two offer
24specific mail-sending strategies.
25
26Additionally the SMTPChannel may be extended to implement very specific
27interaction behaviour with SMTP clients.
28
29The code supports :RFC:`5321`, plus the :rfc:`1870` SIZE and :rfc:`6531`
30SMTPUTF8 extensions.
31
32
33SMTPServer 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
124DebuggingServer 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
134PureProxy 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
145MailmanProxy Objects
146--------------------
147
148
149.. class:: MailmanProxy(localaddr, remoteaddr)
150
151   .. deprecated-removed:: 3.9 3.11
152
153      :class:`MailmanProxy` is deprecated, it depends on a ``Mailman``
154      module which no longer exists and therefore is already broken.
155
156
157   Create a new pure proxy server. Arguments are as per :class:`SMTPServer`.
158   Everything will be relayed to *remoteaddr*, unless local mailman configurations
159   knows about an address, in which case it will be handled via mailman.  Note that
160   running this has a good chance to make you into an open relay, so please be
161   careful.
162
163SMTPChannel Objects
164-------------------
165
166.. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,\
167                       map=None, enable_SMTPUTF8=False, decode_data=False)
168
169   Create a new :class:`SMTPChannel` object which manages the communication
170   between the server and a single SMTP client.
171
172   *conn* and *addr* are as per the instance variables described below.
173
174   *data_size_limit* specifies the maximum number of bytes that will be
175   accepted in a ``DATA`` command.  A value of ``None`` or ``0`` means no
176   limit.
177
178   *enable_SMTPUTF8* determines whether the ``SMTPUTF8`` extension (as defined
179   in :RFC:`6531`) should be enabled.  The default is ``False``.
180   *decode_data* and *enable_SMTPUTF8* cannot be set to ``True`` at the same
181   time.
182
183   A dictionary can be specified in *map* to avoid using a global socket map.
184
185   *decode_data* specifies whether the data portion of the SMTP transaction
186   should be decoded using UTF-8.  The default is ``False``.
187   *decode_data* and *enable_SMTPUTF8* cannot be set to ``True`` at the same
188   time.
189
190   To use a custom SMTPChannel implementation you need to override the
191   :attr:`SMTPServer.channel_class` of your :class:`SMTPServer`.
192
193   .. versionchanged:: 3.5
194      The *decode_data* and *enable_SMTPUTF8* parameters were added.
195
196   .. versionchanged:: 3.6
197      *decode_data* is now ``False`` by default.
198
199   The :class:`SMTPChannel` has the following instance variables:
200
201   .. attribute:: smtp_server
202
203      Holds the :class:`SMTPServer` that spawned this channel.
204
205   .. attribute:: conn
206
207      Holds the socket object connecting to the client.
208
209   .. attribute:: addr
210
211      Holds the address of the client, the second value returned by
212      :func:`socket.accept <socket.socket.accept>`
213
214   .. attribute:: received_lines
215
216      Holds a list of the line strings (decoded using UTF-8) received from
217      the client. The lines have their ``"\r\n"`` line ending translated to
218      ``"\n"``.
219
220   .. attribute:: smtp_state
221
222      Holds the current state of the channel. This will be either
223      :attr:`COMMAND` initially and then :attr:`DATA` after the client sends
224      a "DATA" line.
225
226   .. attribute:: seen_greeting
227
228      Holds a string containing the greeting sent by the client in its "HELO".
229
230   .. attribute:: mailfrom
231
232      Holds a string containing the address identified in the "MAIL FROM:" line
233      from the client.
234
235   .. attribute:: rcpttos
236
237      Holds a list of strings containing the addresses identified in the
238      "RCPT TO:" lines from the client.
239
240   .. attribute:: received_data
241
242      Holds a string containing all of the data sent by the client during the
243      DATA state, up to but not including the terminating ``"\r\n.\r\n"``.
244
245   .. attribute:: fqdn
246
247      Holds the fully-qualified domain name of the server as returned by
248      :func:`socket.getfqdn`.
249
250   .. attribute:: peer
251
252      Holds the name of the client peer as returned by ``conn.getpeername()``
253      where ``conn`` is :attr:`conn`.
254
255   The :class:`SMTPChannel` operates by invoking methods named ``smtp_<command>``
256   upon reception of a command line from the client. Built into the base
257   :class:`SMTPChannel` class are methods for handling the following commands
258   (and responding to them appropriately):
259
260   ======== ===================================================================
261   Command  Action taken
262   ======== ===================================================================
263   HELO     Accepts the greeting from the client and stores it in
264            :attr:`seen_greeting`.  Sets server to base command mode.
265   EHLO     Accepts the greeting from the client and stores it in
266            :attr:`seen_greeting`.  Sets server to extended command mode.
267   NOOP     Takes no action.
268   QUIT     Closes the connection cleanly.
269   MAIL     Accepts the "MAIL FROM:" syntax and stores the supplied address as
270            :attr:`mailfrom`.  In extended command mode, accepts the
271            :rfc:`1870` SIZE attribute and responds appropriately based on the
272            value of *data_size_limit*.
273   RCPT     Accepts the "RCPT TO:" syntax and stores the supplied addresses in
274            the :attr:`rcpttos` list.
275   RSET     Resets the :attr:`mailfrom`, :attr:`rcpttos`, and
276            :attr:`received_data`, but not the greeting.
277   DATA     Sets the internal state to :attr:`DATA` and stores remaining lines
278            from the client in :attr:`received_data` until the terminator
279            ``"\r\n.\r\n"`` is received.
280   HELP     Returns minimal information on command syntax
281   VRFY     Returns code 252 (the server doesn't know if the address is valid)
282   EXPN     Reports that the command is not implemented.
283   ======== ===================================================================
284