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   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
157SMTPChannel 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