Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`smtplib` --- SMTP protocol client |
| 2 | ======================================= |
| 3 | |
| 4 | .. module:: smtplib |
| 5 | :synopsis: SMTP protocol client (requires sockets). |
| 6 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 7 | |
| 8 | |
| 9 | .. index:: |
| 10 | pair: SMTP; protocol |
| 11 | single: Simple Mail Transfer Protocol |
| 12 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 13 | **Source code:** :source:`Lib/smtplib.py` |
| 14 | |
| 15 | -------------- |
| 16 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 17 | The :mod:`smtplib` module defines an SMTP client session object that can be used |
| 18 | to send mail to any Internet machine with an SMTP or ESMTP listener daemon. For |
| 19 | details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer |
| 20 | Protocol) and :rfc:`1869` (SMTP Service Extensions). |
| 21 | |
| 22 | |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 23 | .. class:: SMTP(host='', port=0, local_hostname=None[, timeout], source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 24 | |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 25 | A :class:`SMTP` instance encapsulates an SMTP connection. It has methods |
| 26 | that support a full repertoire of SMTP and ESMTP operations. If the optional |
| 27 | host and port parameters are given, the SMTP :meth:`connect` method is called |
| 28 | with those parameters during initialization. An :exc:`SMTPConnectError` is |
| 29 | raised if the specified host doesn't respond correctly. The optional |
| 30 | *timeout* parameter specifies a timeout in seconds for blocking operations |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 31 | like the connection attempt (if not specified, the global default timeout |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 32 | setting will be used). The optional source_address parameter allows to bind to some |
| 33 | specific source address in a machine with multiple network interfaces, |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 34 | and/or to some specific source TCP port. It takes a 2-tuple (host, port), |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 35 | for the socket to bind to as its source address before connecting. If |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 36 | omitted (or if host or port are ``''`` and/or 0 respectively) the OS default |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 37 | behavior will be used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 38 | |
| 39 | For normal use, you should only require the initialization/connect, |
Jesus Cea | c73f863 | 2012-12-26 16:47:03 +0100 | [diff] [blame] | 40 | :meth:`sendmail`, and :meth:`~smtplib.quit` methods. |
| 41 | An example is included below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
Barry Warsaw | 1f5c958 | 2011-03-15 15:04:44 -0400 | [diff] [blame] | 43 | The :class:`SMTP` class supports the :keyword:`with` statement. When used |
| 44 | like this, the SMTP ``QUIT`` command is issued automatically when the |
| 45 | :keyword:`with` statement exits. E.g.:: |
| 46 | |
| 47 | >>> from smtplib import SMTP |
| 48 | >>> with SMTP("domain.org") as smtp: |
| 49 | ... smtp.noop() |
| 50 | ... |
| 51 | (250, b'Ok') |
| 52 | >>> |
| 53 | |
Antoine Pitrou | 45456a0 | 2011-04-26 18:53:42 +0200 | [diff] [blame] | 54 | .. versionchanged:: 3.3 |
Barry Warsaw | 1f5c958 | 2011-03-15 15:04:44 -0400 | [diff] [blame] | 55 | Support for the :keyword:`with` statement was added. |
| 56 | |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 57 | .. versionchanged:: 3.3 |
| 58 | source_address argument was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 59 | |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 60 | .. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, certfile=None[, timeout], context=None, source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 61 | |
| 62 | A :class:`SMTP_SSL` instance behaves exactly the same as instances of |
| 63 | :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 64 | required from the beginning of the connection and using :meth:`starttls` is |
| 65 | not appropriate. If *host* is not specified, the local host is used. If |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 66 | *port* is zero, the standard SMTP-over-SSL port (465) is used. *keyfile* |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 67 | and *certfile* are also optional, and can contain a PEM formatted private key |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 68 | and certificate chain file for the SSL connection. *context* also optional, can contain |
| 69 | a SSLContext, and is an alternative to keyfile and certfile; If it is specified both |
| 70 | keyfile and certfile must be None. The optional *timeout* |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 71 | parameter specifies a timeout in seconds for blocking operations like the |
Georg Brandl | f78e02b | 2008-06-10 17:40:04 +0000 | [diff] [blame] | 72 | connection attempt (if not specified, the global default timeout setting |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 73 | will be used). The optional source_address parameter allows to bind to some |
| 74 | specific source address in a machine with multiple network interfaces, |
| 75 | and/or to some specific source tcp port. It takes a 2-tuple (host, port), |
| 76 | for the socket to bind to as its source address before connecting. If |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 77 | omitted (or if host or port are ``''`` and/or 0 respectively) the OS default |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 78 | behavior will be used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 80 | .. versionchanged:: 3.3 |
| 81 | *context* was added. |
| 82 | |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 83 | .. versionchanged:: 3.3 |
| 84 | source_address argument was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 85 | |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 86 | |
| 87 | .. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 88 | |
| 89 | The LMTP protocol, which is very similar to ESMTP, is heavily based on the |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 90 | standard SMTP client. It's common to use Unix sockets for LMTP, so our |
| 91 | :meth:`connect` method must support that as well as a regular host:port |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 92 | server. The optional arguments local_hostname and source_address have the |
| 93 | same meaning as that of SMTP client. To specify a Unix socket, you must use |
Senthil Kumaran | 63d4fb4 | 2011-07-30 10:58:30 +0800 | [diff] [blame] | 94 | an absolute path for *host*, starting with a '/'. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 95 | |
| 96 | Authentication is supported, using the regular SMTP mechanism. When using a Unix |
| 97 | socket, LMTP generally don't support or require any authentication, but your |
| 98 | mileage might vary. |
| 99 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | |
| 101 | A nice selection of exceptions is defined as well: |
| 102 | |
| 103 | |
| 104 | .. exception:: SMTPException |
| 105 | |
| 106 | Base exception class for all exceptions raised by this module. |
| 107 | |
| 108 | |
| 109 | .. exception:: SMTPServerDisconnected |
| 110 | |
| 111 | This exception is raised when the server unexpectedly disconnects, or when an |
| 112 | attempt is made to use the :class:`SMTP` instance before connecting it to a |
| 113 | server. |
| 114 | |
| 115 | |
| 116 | .. exception:: SMTPResponseException |
| 117 | |
| 118 | Base class for all exceptions that include an SMTP error code. These exceptions |
| 119 | are generated in some instances when the SMTP server returns an error code. The |
| 120 | error code is stored in the :attr:`smtp_code` attribute of the error, and the |
| 121 | :attr:`smtp_error` attribute is set to the error message. |
| 122 | |
| 123 | |
| 124 | .. exception:: SMTPSenderRefused |
| 125 | |
| 126 | Sender address refused. In addition to the attributes set by on all |
| 127 | :exc:`SMTPResponseException` exceptions, this sets 'sender' to the string that |
| 128 | the SMTP server refused. |
| 129 | |
| 130 | |
| 131 | .. exception:: SMTPRecipientsRefused |
| 132 | |
| 133 | All recipient addresses refused. The errors for each recipient are accessible |
| 134 | through the attribute :attr:`recipients`, which is a dictionary of exactly the |
| 135 | same sort as :meth:`SMTP.sendmail` returns. |
| 136 | |
| 137 | |
| 138 | .. exception:: SMTPDataError |
| 139 | |
| 140 | The SMTP server refused to accept the message data. |
| 141 | |
| 142 | |
| 143 | .. exception:: SMTPConnectError |
| 144 | |
| 145 | Error occurred during establishment of a connection with the server. |
| 146 | |
| 147 | |
| 148 | .. exception:: SMTPHeloError |
| 149 | |
| 150 | The server refused our ``HELO`` message. |
| 151 | |
| 152 | |
| 153 | .. exception:: SMTPAuthenticationError |
| 154 | |
| 155 | SMTP authentication went wrong. Most probably the server didn't accept the |
| 156 | username/password combination provided. |
| 157 | |
| 158 | |
| 159 | .. seealso:: |
| 160 | |
| 161 | :rfc:`821` - Simple Mail Transfer Protocol |
| 162 | Protocol definition for SMTP. This document covers the model, operating |
| 163 | procedure, and protocol details for SMTP. |
| 164 | |
| 165 | :rfc:`1869` - SMTP Service Extensions |
| 166 | Definition of the ESMTP extensions for SMTP. This describes a framework for |
| 167 | extending SMTP with new commands, supporting dynamic discovery of the commands |
| 168 | provided by the server, and defines a few additional commands. |
| 169 | |
| 170 | |
| 171 | .. _smtp-objects: |
| 172 | |
| 173 | SMTP Objects |
| 174 | ------------ |
| 175 | |
| 176 | An :class:`SMTP` instance has the following methods: |
| 177 | |
| 178 | |
| 179 | .. method:: SMTP.set_debuglevel(level) |
| 180 | |
| 181 | Set the debug output level. A true value for *level* results in debug messages |
| 182 | for connection and for all messages sent to and received from the server. |
| 183 | |
| 184 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 185 | .. method:: SMTP.connect(host='localhost', port=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 186 | |
| 187 | Connect to a host on a given port. The defaults are to connect to the local |
| 188 | host at the standard SMTP port (25). If the hostname ends with a colon (``':'``) |
| 189 | followed by a number, that suffix will be stripped off and the number |
| 190 | interpreted as the port number to use. This method is automatically invoked by |
| 191 | the constructor if a host is specified during instantiation. |
| 192 | |
| 193 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 194 | .. method:: SMTP.docmd(cmd, args='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 195 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 196 | Send a command *cmd* to the server. The optional argument *args* is simply |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 197 | concatenated to the command, separated by a space. |
| 198 | |
| 199 | This returns a 2-tuple composed of a numeric response code and the actual |
| 200 | response line (multiline responses are joined into one long line.) |
| 201 | |
| 202 | In normal operation it should not be necessary to call this method explicitly. |
| 203 | It is used to implement other methods and may be useful for testing private |
| 204 | extensions. |
| 205 | |
| 206 | If the connection to the server is lost while waiting for the reply, |
| 207 | :exc:`SMTPServerDisconnected` will be raised. |
| 208 | |
| 209 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 210 | .. method:: SMTP.helo(name='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 211 | |
| 212 | Identify yourself to the SMTP server using ``HELO``. The hostname argument |
| 213 | defaults to the fully qualified domain name of the local host. |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 214 | The message returned by the server is stored as the :attr:`helo_resp` attribute |
| 215 | of the object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 216 | |
| 217 | In normal operation it should not be necessary to call this method explicitly. |
| 218 | It will be implicitly called by the :meth:`sendmail` when necessary. |
| 219 | |
| 220 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 221 | .. method:: SMTP.ehlo(name='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 222 | |
| 223 | Identify yourself to an ESMTP server using ``EHLO``. The hostname argument |
| 224 | defaults to the fully qualified domain name of the local host. Examine the |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 225 | response for ESMTP option and store them for use by :meth:`has_extn`. |
| 226 | Also sets several informational attributes: the message returned by |
| 227 | the server is stored as the :attr:`ehlo_resp` attribute, :attr:`does_esmtp` |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 228 | is set to true or false depending on whether the server supports ESMTP, and |
| 229 | :attr:`esmtp_features` will be a dictionary containing the names of the |
| 230 | SMTP service extensions this server supports, and their |
| 231 | parameters (if any). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
| 233 | Unless you wish to use :meth:`has_extn` before sending mail, it should not be |
| 234 | necessary to call this method explicitly. It will be implicitly called by |
| 235 | :meth:`sendmail` when necessary. |
| 236 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 237 | .. method:: SMTP.ehlo_or_helo_if_needed() |
| 238 | |
| 239 | This method call :meth:`ehlo` and or :meth:`helo` if there has been no |
| 240 | previous ``EHLO`` or ``HELO`` command this session. It tries ESMTP ``EHLO`` |
| 241 | first. |
| 242 | |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 243 | :exc:`SMTPHeloError` |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 244 | The server didn't reply properly to the ``HELO`` greeting. |
| 245 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 246 | .. method:: SMTP.has_extn(name) |
| 247 | |
| 248 | Return :const:`True` if *name* is in the set of SMTP service extensions returned |
| 249 | by the server, :const:`False` otherwise. Case is ignored. |
| 250 | |
| 251 | |
| 252 | .. method:: SMTP.verify(address) |
| 253 | |
| 254 | Check the validity of an address on this server using SMTP ``VRFY``. Returns a |
| 255 | tuple consisting of code 250 and a full :rfc:`822` address (including human |
| 256 | name) if the user address is valid. Otherwise returns an SMTP error code of 400 |
| 257 | or greater and an error string. |
| 258 | |
| 259 | .. note:: |
| 260 | |
| 261 | Many sites disable SMTP ``VRFY`` in order to foil spammers. |
| 262 | |
| 263 | |
| 264 | .. method:: SMTP.login(user, password) |
| 265 | |
| 266 | Log in on an SMTP server that requires authentication. The arguments are the |
| 267 | username and the password to authenticate with. If there has been no previous |
| 268 | ``EHLO`` or ``HELO`` command this session, this method tries ESMTP ``EHLO`` |
| 269 | first. This method will return normally if the authentication was successful, or |
| 270 | may raise the following exceptions: |
| 271 | |
| 272 | :exc:`SMTPHeloError` |
| 273 | The server didn't reply properly to the ``HELO`` greeting. |
| 274 | |
| 275 | :exc:`SMTPAuthenticationError` |
| 276 | The server didn't accept the username/password combination. |
| 277 | |
| 278 | :exc:`SMTPException` |
| 279 | No suitable authentication method was found. |
| 280 | |
| 281 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 282 | .. method:: SMTP.starttls(keyfile=None, certfile=None, context=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 283 | |
| 284 | Put the SMTP connection in TLS (Transport Layer Security) mode. All SMTP |
| 285 | commands that follow will be encrypted. You should then call :meth:`ehlo` |
| 286 | again. |
| 287 | |
| 288 | If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket` |
| 289 | module's :func:`ssl` function. |
| 290 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 291 | Optional *context* parameter is a :class:`ssl.SSLContext` object; This is an alternative to |
| 292 | using a keyfile and a certfile and if specified both *keyfile* and *certfile* should be None. |
| 293 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 294 | If there has been no previous ``EHLO`` or ``HELO`` command this session, |
| 295 | this method tries ESMTP ``EHLO`` first. |
| 296 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 297 | :exc:`SMTPHeloError` |
| 298 | The server didn't reply properly to the ``HELO`` greeting. |
| 299 | |
| 300 | :exc:`SMTPException` |
| 301 | The server does not support the STARTTLS extension. |
| 302 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 303 | :exc:`RuntimeError` |
Ezio Melotti | 0639d5a | 2009-12-19 23:26:38 +0000 | [diff] [blame] | 304 | SSL/TLS support is not available to your Python interpreter. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 305 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 306 | .. versionchanged:: 3.3 |
| 307 | *context* was added. |
| 308 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 309 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 310 | .. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_options=[]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 311 | |
| 312 | Send mail. The required arguments are an :rfc:`822` from-address string, a list |
| 313 | of :rfc:`822` to-address strings (a bare string will be treated as a list with 1 |
| 314 | address), and a message string. The caller may pass a list of ESMTP options |
| 315 | (such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options*. |
| 316 | ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT`` |
| 317 | commands can be passed as *rcpt_options*. (If you need to use different ESMTP |
| 318 | options to different recipients you have to use the low-level methods such as |
| 319 | :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.) |
| 320 | |
| 321 | .. note:: |
| 322 | |
| 323 | The *from_addr* and *to_addrs* parameters are used to construct the message |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 324 | envelope used by the transport agents. ``sendmail`` does not modify the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 325 | message headers in any way. |
| 326 | |
Benjamin Peterson | a6c4a10 | 2011-12-30 23:08:09 -0600 | [diff] [blame] | 327 | *msg* may be a string containing characters in the ASCII range, or a byte |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 328 | string. A string is encoded to bytes using the ascii codec, and lone ``\r`` |
Benjamin Peterson | a6c4a10 | 2011-12-30 23:08:09 -0600 | [diff] [blame] | 329 | and ``\n`` characters are converted to ``\r\n`` characters. A byte string is |
| 330 | not modified. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 331 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 332 | If there has been no previous ``EHLO`` or ``HELO`` command this session, this |
| 333 | method tries ESMTP ``EHLO`` first. If the server does ESMTP, message size and |
| 334 | each of the specified options will be passed to it (if the option is in the |
| 335 | feature set the server advertises). If ``EHLO`` fails, ``HELO`` will be tried |
| 336 | and ESMTP options suppressed. |
| 337 | |
| 338 | This method will return normally if the mail is accepted for at least one |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 339 | recipient. Otherwise it will raise an exception. That is, if this method does |
| 340 | not raise an exception, then someone should get your mail. If this method does |
| 341 | not raise an exception, it returns a dictionary, with one entry for each |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 342 | recipient that was refused. Each entry contains a tuple of the SMTP error code |
| 343 | and the accompanying error message sent by the server. |
| 344 | |
| 345 | This method may raise the following exceptions: |
| 346 | |
| 347 | :exc:`SMTPRecipientsRefused` |
| 348 | All recipients were refused. Nobody got the mail. The :attr:`recipients` |
| 349 | attribute of the exception object is a dictionary with information about the |
| 350 | refused recipients (like the one returned when at least one recipient was |
| 351 | accepted). |
| 352 | |
| 353 | :exc:`SMTPHeloError` |
| 354 | The server didn't reply properly to the ``HELO`` greeting. |
| 355 | |
| 356 | :exc:`SMTPSenderRefused` |
| 357 | The server didn't accept the *from_addr*. |
| 358 | |
| 359 | :exc:`SMTPDataError` |
| 360 | The server replied with an unexpected error code (other than a refusal of a |
| 361 | recipient). |
| 362 | |
| 363 | Unless otherwise noted, the connection will be open even after an exception is |
| 364 | raised. |
| 365 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 366 | .. versionchanged:: 3.2 |
| 367 | *msg* may be a byte string. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 368 | |
| 369 | |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 370 | .. method:: SMTP.send_message(msg, from_addr=None, to_addrs=None, \ |
| 371 | mail_options=[], rcpt_options=[]) |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 372 | |
| 373 | This is a convenience method for calling :meth:`sendmail` with the message |
| 374 | represented by an :class:`email.message.Message` object. The arguments have |
| 375 | the same meaning as for :meth:`sendmail`, except that *msg* is a ``Message`` |
| 376 | object. |
| 377 | |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 378 | If *from_addr* is ``None`` or *to_addrs* is ``None``, ``send_message`` fills |
| 379 | those arguments with addresses extracted from the headers of *msg* as |
| 380 | specified in :rfc:`2822`\: *from_addr* is set to the :mailheader:`Sender` |
| 381 | field if it is present, and otherwise to the :mailheader:`From` field. |
| 382 | *to_adresses* combines the values (if any) of the :mailheader:`To`, |
| 383 | :mailheader:`Cc`, and :mailheader:`Bcc` fields from *msg*. If exactly one |
| 384 | set of :mailheader:`Resent-*` headers appear in the message, the regular |
| 385 | headers are ignored and the :mailheader:`Resent-*` headers are used instead. |
| 386 | If the message contains more than one set of :mailheader:`Resent-*` headers, |
| 387 | a :exc:`ValueError` is raised, since there is no way to unambiguously detect |
| 388 | the most recent set of :mailheader:`Resent-` headers. |
| 389 | |
| 390 | ``send_message`` serializes *msg* using |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 391 | :class:`~email.generator.BytesGenerator` with ``\r\n`` as the *linesep*, and |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 392 | calls :meth:`sendmail` to transmit the resulting message. Regardless of the |
| 393 | values of *from_addr* and *to_addrs*, ``send_message`` does not transmit any |
| 394 | :mailheader:`Bcc` or :mailheader:`Resent-Bcc` headers that may appear |
| 395 | in *msg*. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 396 | |
| 397 | .. versionadded:: 3.2 |
| 398 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 399 | |
| 400 | .. method:: SMTP.quit() |
| 401 | |
Christian Heimes | ba4af49 | 2008-03-28 00:55:15 +0000 | [diff] [blame] | 402 | Terminate the SMTP session and close the connection. Return the result of |
| 403 | the SMTP ``QUIT`` command. |
| 404 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 405 | |
| 406 | Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``, |
| 407 | ``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported. |
| 408 | Normally these do not need to be called directly, so they are not documented |
| 409 | here. For details, consult the module code. |
| 410 | |
| 411 | |
| 412 | .. _smtp-example: |
| 413 | |
| 414 | SMTP Example |
| 415 | ------------ |
| 416 | |
| 417 | This example prompts the user for addresses needed in the message envelope ('To' |
| 418 | and 'From' addresses), and the message to be delivered. Note that the headers |
| 419 | to be included with the message must be included in the message as entered; this |
| 420 | example doesn't do any processing of the :rfc:`822` headers. In particular, the |
| 421 | 'To' and 'From' addresses must be included in the message headers explicitly. :: |
| 422 | |
| 423 | import smtplib |
| 424 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 425 | def prompt(prompt): |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 426 | return input(prompt).strip() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 427 | |
| 428 | fromaddr = prompt("From: ") |
| 429 | toaddrs = prompt("To: ").split() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 430 | print("Enter message, end with ^D (Unix) or ^Z (Windows):") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 431 | |
| 432 | # Add the From: and To: headers at the start! |
| 433 | msg = ("From: %s\r\nTo: %s\r\n\r\n" |
| 434 | % (fromaddr, ", ".join(toaddrs))) |
Collin Winter | 4633448 | 2007-09-10 00:49:57 +0000 | [diff] [blame] | 435 | while True: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 436 | try: |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 437 | line = input() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 438 | except EOFError: |
| 439 | break |
| 440 | if not line: |
| 441 | break |
| 442 | msg = msg + line |
| 443 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 444 | print("Message length is", len(msg)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 445 | |
| 446 | server = smtplib.SMTP('localhost') |
| 447 | server.set_debuglevel(1) |
| 448 | server.sendmail(fromaddr, toaddrs, msg) |
| 449 | server.quit() |
| 450 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 451 | .. note:: |
| 452 | |
| 453 | In general, you will want to use the :mod:`email` package's features to |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 454 | construct an email message, which you can then send |
| 455 | via :meth:`~smtplib.SMTP.send_message`; see :ref:`email-examples`. |