Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`smtpd` --- SMTP Server |
| 2 | ============================ |
| 3 | |
| 4 | .. module:: smtpd |
| 5 | :synopsis: A SMTP server implementation in Python. |
| 6 | |
Andrew Kuchling | 587e970 | 2013-11-12 10:02:35 -0500 | [diff] [blame] | 7 | .. moduleauthor:: Barry Warsaw <barry@python.org> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 8 | .. sectionauthor:: Moshe Zadka <moshez@moshez.org> |
| 9 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 10 | **Source code:** :source:`Lib/smtpd.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 11 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 12 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 13 | |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 14 | This module offers several classes to implement SMTP (email) servers. |
| 15 | |
| 16 | Several server implementations are present; one is a generic |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | do-nothing implementation, which can be overridden, while the other two offer |
| 18 | specific mail-sending strategies. |
| 19 | |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 20 | Additionally the SMTPChannel may be extended to implement very specific |
| 21 | interaction behaviour with SMTP clients. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
R David Murray | d1a30c9 | 2012-05-26 14:33:59 -0400 | [diff] [blame] | 23 | The code supports :RFC:`5321`, plus the :rfc:`1870` SIZE extension. |
| 24 | |
| 25 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | SMTPServer Objects |
| 27 | ------------------ |
| 28 | |
| 29 | |
Serhiy Storchaka | 98b28fd | 2013-10-13 23:12:09 +0300 | [diff] [blame] | 30 | .. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432,\ |
Vinay Sajip | 30298b4 | 2013-06-07 15:21:41 +0100 | [diff] [blame] | 31 | map=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 32 | |
| 33 | Create a new :class:`SMTPServer` object, which binds to local address |
| 34 | *localaddr*. It will treat *remoteaddr* as an upstream SMTP relayer. It |
| 35 | inherits from :class:`asyncore.dispatcher`, and so will insert itself into |
| 36 | :mod:`asyncore`'s event loop on instantiation. |
| 37 | |
R David Murray | d1a30c9 | 2012-05-26 14:33:59 -0400 | [diff] [blame] | 38 | *data_size_limit* specifies the maximum number of bytes that will be |
| 39 | accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no |
| 40 | limit. |
| 41 | |
Vinay Sajip | 30298b4 | 2013-06-07 15:21:41 +0100 | [diff] [blame] | 42 | A dictionary can be specified in *map* to avoid using a global socket map. |
| 43 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 44 | .. method:: process_message(peer, mailfrom, rcpttos, data) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 46 | Raise :exc:`NotImplementedError` exception. Override this in subclasses to |
| 47 | do something useful with this message. Whatever was passed in the |
| 48 | constructor as *remoteaddr* will be available as the :attr:`_remoteaddr` |
| 49 | attribute. *peer* is the remote host's address, *mailfrom* is the envelope |
| 50 | originator, *rcpttos* are the envelope recipients and *data* is a string |
| 51 | containing the contents of the e-mail (which should be in :rfc:`2822` |
| 52 | format). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 53 | |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 54 | .. attribute:: channel_class |
| 55 | |
| 56 | Override this in subclasses to use a custom :class:`SMTPChannel` for |
| 57 | managing SMTP clients. |
| 58 | |
Vinay Sajip | 30298b4 | 2013-06-07 15:21:41 +0100 | [diff] [blame] | 59 | .. versionchanged:: 3.4 |
| 60 | The *map* argument was added. |
| 61 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 62 | |
| 63 | DebuggingServer Objects |
| 64 | ----------------------- |
| 65 | |
| 66 | |
| 67 | .. class:: DebuggingServer(localaddr, remoteaddr) |
| 68 | |
| 69 | Create a new debugging server. Arguments are as per :class:`SMTPServer`. |
| 70 | Messages will be discarded, and printed on stdout. |
| 71 | |
| 72 | |
| 73 | PureProxy Objects |
| 74 | ----------------- |
| 75 | |
| 76 | |
| 77 | .. class:: PureProxy(localaddr, remoteaddr) |
| 78 | |
| 79 | Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. |
| 80 | Everything will be relayed to *remoteaddr*. Note that running this has a good |
| 81 | chance to make you into an open relay, so please be careful. |
| 82 | |
| 83 | |
| 84 | MailmanProxy Objects |
| 85 | -------------------- |
| 86 | |
| 87 | |
| 88 | .. class:: MailmanProxy(localaddr, remoteaddr) |
| 89 | |
| 90 | Create a new pure proxy server. Arguments are as per :class:`SMTPServer`. |
| 91 | Everything will be relayed to *remoteaddr*, unless local mailman configurations |
| 92 | knows about an address, in which case it will be handled via mailman. Note that |
| 93 | running this has a good chance to make you into an open relay, so please be |
| 94 | careful. |
| 95 | |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 96 | SMTPChannel Objects |
| 97 | ------------------- |
| 98 | |
Serhiy Storchaka | 98b28fd | 2013-10-13 23:12:09 +0300 | [diff] [blame] | 99 | .. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432,\ |
Vinay Sajip | 30298b4 | 2013-06-07 15:21:41 +0100 | [diff] [blame] | 100 | map=None)) |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 101 | |
| 102 | Create a new :class:`SMTPChannel` object which manages the communication |
| 103 | between the server and a single SMTP client. |
| 104 | |
Vinay Sajip | 30298b4 | 2013-06-07 15:21:41 +0100 | [diff] [blame] | 105 | *conn* and *addr* are as per the instance variables described below. |
| 106 | |
| 107 | *data_size_limit* specifies the maximum number of bytes that will be |
| 108 | accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no |
| 109 | limit. |
| 110 | |
| 111 | A dictionary can be specified in *map* to avoid using a global socket map. |
| 112 | |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 113 | To use a custom SMTPChannel implementation you need to override the |
| 114 | :attr:`SMTPServer.channel_class` of your :class:`SMTPServer`. |
| 115 | |
| 116 | The :class:`SMTPChannel` has the following instance variables: |
| 117 | |
| 118 | .. attribute:: smtp_server |
| 119 | |
| 120 | Holds the :class:`SMTPServer` that spawned this channel. |
| 121 | |
| 122 | .. attribute:: conn |
| 123 | |
| 124 | Holds the socket object connecting to the client. |
| 125 | |
| 126 | .. attribute:: addr |
| 127 | |
| 128 | Holds the address of the client, the second value returned by |
Ezio Melotti | 8bbcb58 | 2012-09-20 09:06:51 +0300 | [diff] [blame] | 129 | :func:`socket.accept <socket.socket.accept>` |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 130 | |
| 131 | .. attribute:: received_lines |
| 132 | |
| 133 | Holds a list of the line strings (decoded using UTF-8) received from |
Ezio Melotti | 8bbcb58 | 2012-09-20 09:06:51 +0300 | [diff] [blame] | 134 | the client. The lines have their ``"\r\n"`` line ending translated to |
| 135 | ``"\n"``. |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 136 | |
| 137 | .. attribute:: smtp_state |
| 138 | |
| 139 | Holds the current state of the channel. This will be either |
| 140 | :attr:`COMMAND` initially and then :attr:`DATA` after the client sends |
| 141 | a "DATA" line. |
| 142 | |
| 143 | .. attribute:: seen_greeting |
| 144 | |
| 145 | Holds a string containing the greeting sent by the client in its "HELO". |
| 146 | |
| 147 | .. attribute:: mailfrom |
| 148 | |
| 149 | Holds a string containing the address identified in the "MAIL FROM:" line |
| 150 | from the client. |
| 151 | |
| 152 | .. attribute:: rcpttos |
| 153 | |
| 154 | Holds a list of strings containing the addresses identified in the |
| 155 | "RCPT TO:" lines from the client. |
| 156 | |
| 157 | .. attribute:: received_data |
| 158 | |
| 159 | Holds a string containing all of the data sent by the client during the |
Ezio Melotti | 8bbcb58 | 2012-09-20 09:06:51 +0300 | [diff] [blame] | 160 | DATA state, up to but not including the terminating ``"\r\n.\r\n"``. |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 161 | |
| 162 | .. attribute:: fqdn |
| 163 | |
| 164 | Holds the fully-qualified domain name of the server as returned by |
Ezio Melotti | 8bbcb58 | 2012-09-20 09:06:51 +0300 | [diff] [blame] | 165 | :func:`socket.getfqdn`. |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 166 | |
| 167 | .. attribute:: peer |
| 168 | |
| 169 | Holds the name of the client peer as returned by ``conn.getpeername()`` |
| 170 | where ``conn`` is :attr:`conn`. |
| 171 | |
| 172 | The :class:`SMTPChannel` operates by invoking methods named ``smtp_<command>`` |
| 173 | upon reception of a command line from the client. Built into the base |
| 174 | :class:`SMTPChannel` class are methods for handling the following commands |
| 175 | (and responding to them appropriately): |
| 176 | |
| 177 | ======== =================================================================== |
| 178 | Command Action taken |
| 179 | ======== =================================================================== |
| 180 | HELO Accepts the greeting from the client and stores it in |
R David Murray | d1a30c9 | 2012-05-26 14:33:59 -0400 | [diff] [blame] | 181 | :attr:`seen_greeting`. Sets server to base command mode. |
| 182 | EHLO Accepts the greeting from the client and stores it in |
| 183 | :attr:`seen_greeting`. Sets server to extended command mode. |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 184 | NOOP Takes no action. |
| 185 | QUIT Closes the connection cleanly. |
| 186 | MAIL Accepts the "MAIL FROM:" syntax and stores the supplied address as |
R David Murray | d1a30c9 | 2012-05-26 14:33:59 -0400 | [diff] [blame] | 187 | :attr:`mailfrom`. In extended command mode, accepts the |
| 188 | :rfc:`1870` SIZE attribute and responds appropriately based on the |
Ezio Melotti | a58d8b0 | 2012-09-20 09:09:24 +0300 | [diff] [blame] | 189 | value of *data_size_limit*. |
Richard Jones | 803ef8a | 2010-07-24 09:51:40 +0000 | [diff] [blame] | 190 | RCPT Accepts the "RCPT TO:" syntax and stores the supplied addresses in |
| 191 | the :attr:`rcpttos` list. |
| 192 | RSET Resets the :attr:`mailfrom`, :attr:`rcpttos`, and |
| 193 | :attr:`received_data`, but not the greeting. |
| 194 | DATA Sets the internal state to :attr:`DATA` and stores remaining lines |
| 195 | from the client in :attr:`received_data` until the terminator |
Ezio Melotti | 8bbcb58 | 2012-09-20 09:06:51 +0300 | [diff] [blame] | 196 | ``"\r\n.\r\n"`` is received. |
R David Murray | d1a30c9 | 2012-05-26 14:33:59 -0400 | [diff] [blame] | 197 | HELP Returns minimal information on command syntax |
| 198 | VRFY Returns code 252 (the server doesn't know if the address is valid) |
| 199 | EXPN Reports that the command is not implemented. |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 200 | ======== =================================================================== |