summaryrefslogtreecommitdiffstats
path: root/Doc/library/smtpd.rst
blob: e383201aab1461c597e7d0ba0ec05e5d738aa4a8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
: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=False)

   Create a new :class:`SMTPServer` object, which binds to local address
   *localaddr*.  It will treat *remoteaddr* as an upstream SMTP relayer.  Both
   *localaddr* and *remoteaddr* should be a :ref:`(host, port) <host_port>`
   tuple.  The object 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.

   *map* is the socket map to use for connections (an initially empty
   dictionary is a suitable value).  If not specified the :mod:`asyncore`
   global socket map is used.

   *enable_SMTPUTF8* determines whether the ``SMTPUTF8`` extension (as defined
   in :RFC:`6531`) should be enabled.  The default is ``False``.
   When ``True``, ``SMTPUTF8`` is accepted as a parameter to the ``MAIL``
   command and when present is passed to :meth:`process_message` in the
   ``kwargs['mail_options']`` list.  *decode_data* and *enable_SMTPUTF8*
   cannot be set to ``True`` at the same time.

   *decode_data* specifies whether the data portion of the SMTP transaction
   should be decoded using UTF-8.  When *decode_data* is ``False`` (the
   default), the server advertises the ``8BITMIME``
   extension (:rfc:`6152`), accepts the ``BODY=8BITMIME`` parameter to
   the ``MAIL`` command, and when present passes it to :meth:`process_message`
   in the ``kwargs['mail_options']`` list. *decode_data* and *enable_SMTPUTF8*
   cannot be set to ``True`` at the same time.

   .. method:: process_message(peer, mailfrom, rcpttos, data, **kwargs)

      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.

      *kwargs* is a dictionary containing additional information. It is empty
      if ``decode_data=True`` was given as an init argument, otherwise
      it contains the following keys:

          *mail_options*:
             a list of all received parameters to the ``MAIL``
             command (the elements are uppercase strings; example:
             ``['BODY=8BITMIME', 'SMTPUTF8']``).

          *rcpt_options*:
             same as *mail_options* but for the ``RCPT`` command.
             Currently no ``RCPT TO`` options are supported, so for now
             this will always be an empty list.

      Implementations of ``process_message`` should use the ``**kwargs``
      signature to accept arbitrary keyword arguments, since future feature
      enhancements may add keys to the kwargs dictionary.

      Return ``None`` to request a normal ``250 Ok`` response; otherwise
      return the desired response string in :RFC:`5321` format.

   .. attribute:: channel_class

      Override this in subclasses to use a custom :class:`SMTPChannel` for
      managing SMTP clients.

   .. versionadded:: 3.4
      The *map* constructor argument.

   .. versionchanged:: 3.5
      *localaddr* and *remoteaddr* may now contain IPv6 addresses.

   .. versionadded:: 3.5
      The *decode_data* and *enable_SMTPUTF8* constructor parameters, and the
      *kwargs* parameter to :meth:`process_message` when *decode_data* is
      ``False``.

   .. versionchanged:: 3.6
      *decode_data* is now ``False`` by default.


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=False)

   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* determines whether the ``SMTPUTF8`` extension (as defined
   in :RFC:`6531`) should be enabled.  The default is ``False``.
   *decode_data* and *enable_SMTPUTF8* cannot be 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 ``False``.
   *decode_data* and *enable_SMTPUTF8* cannot be set to ``True`` at the same
   time.

   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* parameters were added.

   .. versionchanged:: 3.6
      *decode_data* is now ``False`` by default.

   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.
   ======== ===================================================================