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). |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 7 | .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
| 8 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 9 | **Source code:** :source:`Lib/smtplib.py` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
| 11 | .. index:: |
| 12 | pair: SMTP; protocol |
| 13 | single: Simple Mail Transfer Protocol |
| 14 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 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 | |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 25 | An :class:`SMTP` instance encapsulates an SMTP connection. It has methods |
Alexandre Vassalotti | 5f8ced2 | 2008-05-16 00:03:33 +0000 | [diff] [blame] | 26 | that support a full repertoire of SMTP and ESMTP operations. If the optional |
R David Murray | 021362d | 2013-06-23 16:05:44 -0400 | [diff] [blame] | 27 | host and port parameters are given, the SMTP :meth:`connect` method is |
| 28 | called with those parameters during initialization. If specified, |
| 29 | *local_hostname* is used as the FQDN of the local host in the HELO/EHLO |
| 30 | command. Otherwise, the local hostname is found using |
| 31 | :func:`socket.getfqdn`. If the :meth:`connect` call returns anything other |
| 32 | than a success code, an :exc:`SMTPConnectError` is raised. The optional |
| 33 | *timeout* parameter specifies a timeout in seconds for blocking operations |
| 34 | like the connection attempt (if not specified, the global default timeout |
R David Murray | 6ceca4e | 2014-06-09 16:41:06 -0400 | [diff] [blame] | 35 | setting will be used). If the timeout expires, :exc:`socket.timeout` is |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 36 | raised. The optional source_address parameter allows binding |
R David Murray | 021362d | 2013-06-23 16:05:44 -0400 | [diff] [blame] | 37 | to some specific source address in a machine with multiple network |
| 38 | interfaces, and/or to some specific source TCP port. It takes a 2-tuple |
| 39 | (host, port), for the socket to bind to as its source address before |
| 40 | connecting. If omitted (or if host or port are ``''`` and/or 0 respectively) |
| 41 | the OS default behavior will be used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 42 | |
| 43 | For normal use, you should only require the initialization/connect, |
Jesus Cea | c73f863 | 2012-12-26 16:47:03 +0100 | [diff] [blame] | 44 | :meth:`sendmail`, and :meth:`~smtplib.quit` methods. |
| 45 | An example is included below. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Barry Warsaw | 1f5c958 | 2011-03-15 15:04:44 -0400 | [diff] [blame] | 47 | The :class:`SMTP` class supports the :keyword:`with` statement. When used |
| 48 | like this, the SMTP ``QUIT`` command is issued automatically when the |
| 49 | :keyword:`with` statement exits. E.g.:: |
| 50 | |
| 51 | >>> from smtplib import SMTP |
| 52 | >>> with SMTP("domain.org") as smtp: |
| 53 | ... smtp.noop() |
| 54 | ... |
| 55 | (250, b'Ok') |
| 56 | >>> |
| 57 | |
Antoine Pitrou | 45456a0 | 2011-04-26 18:53:42 +0200 | [diff] [blame] | 58 | .. versionchanged:: 3.3 |
Barry Warsaw | 1f5c958 | 2011-03-15 15:04:44 -0400 | [diff] [blame] | 59 | Support for the :keyword:`with` statement was added. |
| 60 | |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 61 | .. versionchanged:: 3.3 |
| 62 | source_address argument was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 63 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 64 | .. versionadded:: 3.5 |
| 65 | The SMTPUTF8 extension (:rfc:`6531`) is now supported. |
| 66 | |
| 67 | |
R David Murray | 36beb66 | 2013-06-23 15:47:50 -0400 | [diff] [blame] | 68 | .. class:: SMTP_SSL(host='', port=0, local_hostname=None, keyfile=None, \ |
| 69 | certfile=None [, timeout], context=None, \ |
| 70 | source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 71 | |
Martin Panter | 7462b649 | 2015-11-02 03:37:02 +0000 | [diff] [blame] | 72 | An :class:`SMTP_SSL` instance behaves exactly the same as instances of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 73 | :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] | 74 | required from the beginning of the connection and using :meth:`starttls` is |
| 75 | not appropriate. If *host* is not specified, the local host is used. If |
R David Murray | 36beb66 | 2013-06-23 15:47:50 -0400 | [diff] [blame] | 76 | *port* is zero, the standard SMTP-over-SSL port (465) is used. The optional |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 77 | arguments *local_hostname*, *timeout* and *source_address* have the same |
| 78 | meaning as they do in the :class:`SMTP` class. *context*, also optional, |
Martin Panter | c04fb56 | 2016-02-10 05:44:01 +0000 | [diff] [blame] | 79 | can contain a :class:`~ssl.SSLContext` and allows configuring various |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 80 | aspects of the secure connection. Please read :ref:`ssl-security` for |
| 81 | best practices. |
| 82 | |
| 83 | *keyfile* and *certfile* are a legacy alternative to *context*, and can |
| 84 | point to a PEM formatted private key and certificate chain file for the |
| 85 | SSL connection. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 87 | .. versionchanged:: 3.3 |
| 88 | *context* was added. |
| 89 | |
Senthil Kumaran | b351a48 | 2011-07-31 09:14:17 +0800 | [diff] [blame] | 90 | .. versionchanged:: 3.3 |
| 91 | source_address argument was added. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | |
Christian Heimes | a5768f7 | 2013-12-02 20:44:17 +0100 | [diff] [blame] | 93 | .. versionchanged:: 3.4 |
| 94 | The class now supports hostname check with |
Antoine Pitrou | c5e075f | 2014-03-22 18:19:11 +0100 | [diff] [blame] | 95 | :attr:`ssl.SSLContext.check_hostname` and *Server Name Indication* (see |
| 96 | :data:`ssl.HAS_SNI`). |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 97 | |
Christian Heimes | d048637 | 2016-09-10 23:23:33 +0200 | [diff] [blame] | 98 | .. deprecated:: 3.6 |
| 99 | |
| 100 | *keyfile* and *certfile* are deprecated in favor of *context*. |
| 101 | Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let |
| 102 | :func:`ssl.create_default_context` select the system's trusted CA |
| 103 | certificates for you. |
| 104 | |
| 105 | |
Senthil Kumaran | 3d23fd6 | 2011-07-30 10:56:50 +0800 | [diff] [blame] | 106 | .. class:: LMTP(host='', port=LMTP_PORT, local_hostname=None, source_address=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 107 | |
| 108 | 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] | 109 | standard SMTP client. It's common to use Unix sockets for LMTP, so our |
| 110 | :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] | 111 | server. The optional arguments local_hostname and source_address have the |
R David Murray | 021362d | 2013-06-23 16:05:44 -0400 | [diff] [blame] | 112 | same meaning as they do in the :class:`SMTP` class. To specify a Unix |
| 113 | socket, you must use an absolute path for *host*, starting with a '/'. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 114 | |
R David Murray | 021362d | 2013-06-23 16:05:44 -0400 | [diff] [blame] | 115 | Authentication is supported, using the regular SMTP mechanism. When using a |
| 116 | Unix socket, LMTP generally don't support or require any authentication, but |
| 117 | your mileage might vary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | |
| 120 | A nice selection of exceptions is defined as well: |
| 121 | |
| 122 | |
| 123 | .. exception:: SMTPException |
| 124 | |
R David Murray | 8a34596 | 2013-04-14 06:46:35 -0400 | [diff] [blame] | 125 | Subclass of :exc:`OSError` that is the base exception class for all |
Ned Deily | 7cf5e61 | 2013-08-13 01:15:14 -0700 | [diff] [blame] | 126 | the other exceptions provided by this module. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 127 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 128 | .. versionchanged:: 3.4 |
| 129 | SMTPException became subclass of :exc:`OSError` |
| 130 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | .. exception:: SMTPServerDisconnected |
| 133 | |
| 134 | This exception is raised when the server unexpectedly disconnects, or when an |
| 135 | attempt is made to use the :class:`SMTP` instance before connecting it to a |
| 136 | server. |
| 137 | |
| 138 | |
| 139 | .. exception:: SMTPResponseException |
| 140 | |
| 141 | Base class for all exceptions that include an SMTP error code. These exceptions |
| 142 | are generated in some instances when the SMTP server returns an error code. The |
| 143 | error code is stored in the :attr:`smtp_code` attribute of the error, and the |
| 144 | :attr:`smtp_error` attribute is set to the error message. |
| 145 | |
| 146 | |
| 147 | .. exception:: SMTPSenderRefused |
| 148 | |
| 149 | Sender address refused. In addition to the attributes set by on all |
| 150 | :exc:`SMTPResponseException` exceptions, this sets 'sender' to the string that |
| 151 | the SMTP server refused. |
| 152 | |
| 153 | |
| 154 | .. exception:: SMTPRecipientsRefused |
| 155 | |
| 156 | All recipient addresses refused. The errors for each recipient are accessible |
| 157 | through the attribute :attr:`recipients`, which is a dictionary of exactly the |
| 158 | same sort as :meth:`SMTP.sendmail` returns. |
| 159 | |
| 160 | |
| 161 | .. exception:: SMTPDataError |
| 162 | |
| 163 | The SMTP server refused to accept the message data. |
| 164 | |
| 165 | |
| 166 | .. exception:: SMTPConnectError |
| 167 | |
| 168 | Error occurred during establishment of a connection with the server. |
| 169 | |
| 170 | |
| 171 | .. exception:: SMTPHeloError |
| 172 | |
| 173 | The server refused our ``HELO`` message. |
| 174 | |
| 175 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 176 | .. exception:: SMTPNotSupportedError |
| 177 | |
| 178 | The command or option attempted is not supported by the server. |
| 179 | |
| 180 | .. versionadded:: 3.5 |
| 181 | |
| 182 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | .. exception:: SMTPAuthenticationError |
| 184 | |
| 185 | SMTP authentication went wrong. Most probably the server didn't accept the |
| 186 | username/password combination provided. |
| 187 | |
| 188 | |
| 189 | .. seealso:: |
| 190 | |
| 191 | :rfc:`821` - Simple Mail Transfer Protocol |
| 192 | Protocol definition for SMTP. This document covers the model, operating |
| 193 | procedure, and protocol details for SMTP. |
| 194 | |
| 195 | :rfc:`1869` - SMTP Service Extensions |
| 196 | Definition of the ESMTP extensions for SMTP. This describes a framework for |
| 197 | extending SMTP with new commands, supporting dynamic discovery of the commands |
| 198 | provided by the server, and defines a few additional commands. |
| 199 | |
| 200 | |
| 201 | .. _smtp-objects: |
| 202 | |
| 203 | SMTP Objects |
| 204 | ------------ |
| 205 | |
| 206 | An :class:`SMTP` instance has the following methods: |
| 207 | |
| 208 | |
| 209 | .. method:: SMTP.set_debuglevel(level) |
| 210 | |
R David Murray | 2e6ad42 | 2015-04-16 17:24:52 -0400 | [diff] [blame] | 211 | Set the debug output level. A value of 1 or ``True`` for *level* results in |
| 212 | debug messages for connection and for all messages sent to and received from |
| 213 | the server. A value of 2 for *level* results in these messages being |
| 214 | timestamped. |
| 215 | |
| 216 | .. versionchanged:: 3.5 Added debuglevel 2. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 217 | |
| 218 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 219 | .. method:: SMTP.docmd(cmd, args='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 220 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 221 | 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] | 222 | concatenated to the command, separated by a space. |
| 223 | |
| 224 | This returns a 2-tuple composed of a numeric response code and the actual |
| 225 | response line (multiline responses are joined into one long line.) |
| 226 | |
| 227 | In normal operation it should not be necessary to call this method explicitly. |
| 228 | It is used to implement other methods and may be useful for testing private |
| 229 | extensions. |
| 230 | |
| 231 | If the connection to the server is lost while waiting for the reply, |
| 232 | :exc:`SMTPServerDisconnected` will be raised. |
| 233 | |
| 234 | |
R David Murray | 14ee3cf | 2013-04-13 14:40:33 -0400 | [diff] [blame] | 235 | .. method:: SMTP.connect(host='localhost', port=0) |
| 236 | |
| 237 | Connect to a host on a given port. The defaults are to connect to the local |
| 238 | host at the standard SMTP port (25). If the hostname ends with a colon (``':'``) |
| 239 | followed by a number, that suffix will be stripped off and the number |
| 240 | interpreted as the port number to use. This method is automatically invoked by |
| 241 | the constructor if a host is specified during instantiation. Returns a |
| 242 | 2-tuple of the response code and message sent by the server in its |
| 243 | connection response. |
| 244 | |
| 245 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 246 | .. method:: SMTP.helo(name='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 247 | |
| 248 | Identify yourself to the SMTP server using ``HELO``. The hostname argument |
| 249 | defaults to the fully qualified domain name of the local host. |
Benjamin Peterson | ae5360b | 2008-09-08 23:05:23 +0000 | [diff] [blame] | 250 | The message returned by the server is stored as the :attr:`helo_resp` attribute |
| 251 | of the object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 252 | |
| 253 | In normal operation it should not be necessary to call this method explicitly. |
| 254 | It will be implicitly called by the :meth:`sendmail` when necessary. |
| 255 | |
| 256 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 257 | .. method:: SMTP.ehlo(name='') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 258 | |
| 259 | Identify yourself to an ESMTP server using ``EHLO``. The hostname argument |
| 260 | 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] | 261 | response for ESMTP option and store them for use by :meth:`has_extn`. |
| 262 | Also sets several informational attributes: the message returned by |
| 263 | 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] | 264 | is set to true or false depending on whether the server supports ESMTP, and |
| 265 | :attr:`esmtp_features` will be a dictionary containing the names of the |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 266 | SMTP service extensions this server supports, and their parameters (if any). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 267 | |
| 268 | Unless you wish to use :meth:`has_extn` before sending mail, it should not be |
| 269 | necessary to call this method explicitly. It will be implicitly called by |
| 270 | :meth:`sendmail` when necessary. |
| 271 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 272 | .. method:: SMTP.ehlo_or_helo_if_needed() |
| 273 | |
Ville Skyttä | da12063 | 2018-08-13 06:39:19 +0300 | [diff] [blame^] | 274 | This method calls :meth:`ehlo` and/or :meth:`helo` if there has been no |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 275 | previous ``EHLO`` or ``HELO`` command this session. It tries ESMTP ``EHLO`` |
| 276 | first. |
| 277 | |
Georg Brandl | 1f01deb | 2009-01-03 22:47:39 +0000 | [diff] [blame] | 278 | :exc:`SMTPHeloError` |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 279 | The server didn't reply properly to the ``HELO`` greeting. |
| 280 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 281 | .. method:: SMTP.has_extn(name) |
| 282 | |
| 283 | Return :const:`True` if *name* is in the set of SMTP service extensions returned |
| 284 | by the server, :const:`False` otherwise. Case is ignored. |
| 285 | |
| 286 | |
| 287 | .. method:: SMTP.verify(address) |
| 288 | |
| 289 | Check the validity of an address on this server using SMTP ``VRFY``. Returns a |
| 290 | tuple consisting of code 250 and a full :rfc:`822` address (including human |
| 291 | name) if the user address is valid. Otherwise returns an SMTP error code of 400 |
| 292 | or greater and an error string. |
| 293 | |
| 294 | .. note:: |
| 295 | |
| 296 | Many sites disable SMTP ``VRFY`` in order to foil spammers. |
| 297 | |
| 298 | |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 299 | .. method:: SMTP.login(user, password, *, initial_response_ok=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | |
| 301 | Log in on an SMTP server that requires authentication. The arguments are the |
| 302 | username and the password to authenticate with. If there has been no previous |
| 303 | ``EHLO`` or ``HELO`` command this session, this method tries ESMTP ``EHLO`` |
| 304 | first. This method will return normally if the authentication was successful, or |
| 305 | may raise the following exceptions: |
| 306 | |
| 307 | :exc:`SMTPHeloError` |
| 308 | The server didn't reply properly to the ``HELO`` greeting. |
| 309 | |
| 310 | :exc:`SMTPAuthenticationError` |
| 311 | The server didn't accept the username/password combination. |
| 312 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 313 | :exc:`SMTPNotSupportedError` |
| 314 | The ``AUTH`` command is not supported by the server. |
| 315 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | :exc:`SMTPException` |
| 317 | No suitable authentication method was found. |
| 318 | |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 319 | Each of the authentication methods supported by :mod:`smtplib` are tried in |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 320 | turn if they are advertised as supported by the server. See :meth:`auth` |
| 321 | for a list of supported authentication methods. *initial_response_ok* is |
| 322 | passed through to :meth:`auth`. |
| 323 | |
| 324 | Optional keyword argument *initial_response_ok* specifies whether, for |
| 325 | authentication methods that support it, an "initial response" as specified |
| 326 | in :rfc:`4954` can be sent along with the ``AUTH`` command, rather than |
| 327 | requiring a challenge/response. |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 328 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 329 | .. versionchanged:: 3.5 |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 330 | :exc:`SMTPNotSupportedError` may be raised, and the |
| 331 | *initial_response_ok* parameter was added. |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 332 | |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 333 | |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 334 | .. method:: SMTP.auth(mechanism, authobject, *, initial_response_ok=True) |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 335 | |
| 336 | Issue an ``SMTP`` ``AUTH`` command for the specified authentication |
| 337 | *mechanism*, and handle the challenge response via *authobject*. |
| 338 | |
| 339 | *mechanism* specifies which authentication mechanism is to |
| 340 | be used as argument to the ``AUTH`` command; the valid values are |
| 341 | those listed in the ``auth`` element of :attr:`esmtp_features`. |
| 342 | |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 343 | *authobject* must be a callable object taking an optional single argument: |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 344 | |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 345 | data = authobject(challenge=None) |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 346 | |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 347 | If optional keyword argument *initial_response_ok* is true, |
| 348 | ``authobject()`` will be called first with no argument. It can return the |
| 349 | :rfc:`4954` "initial response" bytes which will be encoded and sent with |
| 350 | the ``AUTH`` command as below. If the ``authobject()`` does not support an |
| 351 | initial response (e.g. because it requires a challenge), it should return |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 352 | ``None`` when called with ``challenge=None``. If *initial_response_ok* is |
| 353 | false, then ``authobject()`` will not be called first with ``None``. |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 354 | |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 355 | If the initial response check returns ``None``, or if *initial_response_ok* is |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 356 | false, ``authobject()`` will be called to process the server's challenge |
| 357 | response; the *challenge* argument it is passed will be a ``bytes``. It |
| 358 | should return ``bytes`` *data* that will be base64 encoded and sent to the |
| 359 | server. |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 360 | |
| 361 | The ``SMTP`` class provides ``authobjects`` for the ``CRAM-MD5``, ``PLAIN``, |
| 362 | and ``LOGIN`` mechanisms; they are named ``SMTP.auth_cram_md5``, |
| 363 | ``SMTP.auth_plain``, and ``SMTP.auth_login`` respectively. They all require |
| 364 | that the ``user`` and ``password`` properties of the ``SMTP`` instance are |
| 365 | set to appropriate values. |
| 366 | |
| 367 | User code does not normally need to call ``auth`` directly, but can instead |
Barry Warsaw | c5ea754 | 2015-07-09 10:39:55 -0400 | [diff] [blame] | 368 | call the :meth:`login` method, which will try each of the above mechanisms |
| 369 | in turn, in the order listed. ``auth`` is exposed to facilitate the |
| 370 | implementation of authentication methods not (or not yet) supported |
| 371 | directly by :mod:`smtplib`. |
R David Murray | 76e13c1 | 2014-07-03 14:47:46 -0400 | [diff] [blame] | 372 | |
| 373 | .. versionadded:: 3.5 |
| 374 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 375 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 376 | .. method:: SMTP.starttls(keyfile=None, certfile=None, context=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 377 | |
| 378 | Put the SMTP connection in TLS (Transport Layer Security) mode. All SMTP |
| 379 | commands that follow will be encrypted. You should then call :meth:`ehlo` |
| 380 | again. |
| 381 | |
Ville Skyttä | da12063 | 2018-08-13 06:39:19 +0300 | [diff] [blame^] | 382 | If *keyfile* and *certfile* are provided, they are used to create an |
| 383 | :class:`ssl.SSLContext`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 384 | |
Ville Skyttä | da12063 | 2018-08-13 06:39:19 +0300 | [diff] [blame^] | 385 | Optional *context* parameter is an :class:`ssl.SSLContext` object; This is |
Serhiy Storchaka | ecf41da | 2016-10-19 16:29:26 +0300 | [diff] [blame] | 386 | an alternative to using a keyfile and a certfile and if specified both |
| 387 | *keyfile* and *certfile* should be ``None``. |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 388 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 389 | If there has been no previous ``EHLO`` or ``HELO`` command this session, |
| 390 | this method tries ESMTP ``EHLO`` first. |
| 391 | |
Ville Skyttä | da12063 | 2018-08-13 06:39:19 +0300 | [diff] [blame^] | 392 | .. deprecated:: 3.6 |
| 393 | |
| 394 | *keyfile* and *certfile* are deprecated in favor of *context*. |
| 395 | Please use :meth:`ssl.SSLContext.load_cert_chain` instead, or let |
| 396 | :func:`ssl.create_default_context` select the system's trusted CA |
| 397 | certificates for you. |
| 398 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 399 | :exc:`SMTPHeloError` |
| 400 | The server didn't reply properly to the ``HELO`` greeting. |
| 401 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 402 | :exc:`SMTPNotSupportedError` |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 403 | The server does not support the STARTTLS extension. |
| 404 | |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 405 | :exc:`RuntimeError` |
Ezio Melotti | 0639d5a | 2009-12-19 23:26:38 +0000 | [diff] [blame] | 406 | SSL/TLS support is not available to your Python interpreter. |
Christian Heimes | 679db4a | 2008-01-18 09:56:22 +0000 | [diff] [blame] | 407 | |
Antoine Pitrou | e065020 | 2011-05-18 18:03:09 +0200 | [diff] [blame] | 408 | .. versionchanged:: 3.3 |
| 409 | *context* was added. |
| 410 | |
Christian Heimes | a5768f7 | 2013-12-02 20:44:17 +0100 | [diff] [blame] | 411 | .. versionchanged:: 3.4 |
| 412 | The method now supports hostname check with |
| 413 | :attr:`SSLContext.check_hostname` and *Server Name Indicator* (see |
| 414 | :data:`~ssl.HAS_SNI`). |
| 415 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 416 | .. versionchanged:: 3.5 |
| 417 | The error raised for lack of STARTTLS support is now the |
| 418 | :exc:`SMTPNotSupportedError` subclass instead of the base |
| 419 | :exc:`SMTPException`. |
| 420 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 421 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 422 | .. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_options=[]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 423 | |
| 424 | Send mail. The required arguments are an :rfc:`822` from-address string, a list |
| 425 | of :rfc:`822` to-address strings (a bare string will be treated as a list with 1 |
| 426 | address), and a message string. The caller may pass a list of ESMTP options |
| 427 | (such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options*. |
| 428 | ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT`` |
| 429 | commands can be passed as *rcpt_options*. (If you need to use different ESMTP |
| 430 | options to different recipients you have to use the low-level methods such as |
| 431 | :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.) |
| 432 | |
| 433 | .. note:: |
| 434 | |
| 435 | 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] | 436 | envelope used by the transport agents. ``sendmail`` does not modify the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 437 | message headers in any way. |
| 438 | |
Benjamin Peterson | a6c4a10 | 2011-12-30 23:08:09 -0600 | [diff] [blame] | 439 | *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] | 440 | 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] | 441 | and ``\n`` characters are converted to ``\r\n`` characters. A byte string is |
| 442 | not modified. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 443 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 444 | If there has been no previous ``EHLO`` or ``HELO`` command this session, this |
| 445 | method tries ESMTP ``EHLO`` first. If the server does ESMTP, message size and |
| 446 | each of the specified options will be passed to it (if the option is in the |
| 447 | feature set the server advertises). If ``EHLO`` fails, ``HELO`` will be tried |
| 448 | and ESMTP options suppressed. |
| 449 | |
| 450 | 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] | 451 | recipient. Otherwise it will raise an exception. That is, if this method does |
| 452 | not raise an exception, then someone should get your mail. If this method does |
| 453 | 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] | 454 | recipient that was refused. Each entry contains a tuple of the SMTP error code |
| 455 | and the accompanying error message sent by the server. |
| 456 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 457 | If ``SMTPUTF8`` is included in *mail_options*, and the server supports it, |
Raymond Hettinger | 624e222 | 2016-08-30 13:25:06 -0700 | [diff] [blame] | 458 | *from_addr* and *to_addrs* may contain non-ASCII characters. |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 459 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 460 | This method may raise the following exceptions: |
| 461 | |
| 462 | :exc:`SMTPRecipientsRefused` |
| 463 | All recipients were refused. Nobody got the mail. The :attr:`recipients` |
| 464 | attribute of the exception object is a dictionary with information about the |
| 465 | refused recipients (like the one returned when at least one recipient was |
| 466 | accepted). |
| 467 | |
| 468 | :exc:`SMTPHeloError` |
| 469 | The server didn't reply properly to the ``HELO`` greeting. |
| 470 | |
| 471 | :exc:`SMTPSenderRefused` |
| 472 | The server didn't accept the *from_addr*. |
| 473 | |
| 474 | :exc:`SMTPDataError` |
| 475 | The server replied with an unexpected error code (other than a refusal of a |
| 476 | recipient). |
| 477 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 478 | :exc:`SMTPNotSupportedError` |
| 479 | ``SMTPUTF8`` was given in the *mail_options* but is not supported by the |
| 480 | server. |
| 481 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 482 | Unless otherwise noted, the connection will be open even after an exception is |
| 483 | raised. |
| 484 | |
Georg Brandl | 61063cc | 2012-06-24 22:48:30 +0200 | [diff] [blame] | 485 | .. versionchanged:: 3.2 |
| 486 | *msg* may be a byte string. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 487 | |
R David Murray | cee7cf6 | 2015-05-16 13:58:14 -0400 | [diff] [blame] | 488 | .. versionchanged:: 3.5 |
| 489 | ``SMTPUTF8`` support added, and :exc:`SMTPNotSupportedError` may be |
| 490 | raised if ``SMTPUTF8`` is specified but the server does not support it. |
| 491 | |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 492 | |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 493 | .. method:: SMTP.send_message(msg, from_addr=None, to_addrs=None, \ |
| 494 | mail_options=[], rcpt_options=[]) |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 495 | |
| 496 | This is a convenience method for calling :meth:`sendmail` with the message |
| 497 | represented by an :class:`email.message.Message` object. The arguments have |
| 498 | the same meaning as for :meth:`sendmail`, except that *msg* is a ``Message`` |
| 499 | object. |
| 500 | |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 501 | If *from_addr* is ``None`` or *to_addrs* is ``None``, ``send_message`` fills |
| 502 | those arguments with addresses extracted from the headers of *msg* as |
R David Murray | 8308444 | 2015-05-17 19:27:22 -0400 | [diff] [blame] | 503 | specified in :rfc:`5322`\: *from_addr* is set to the :mailheader:`Sender` |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 504 | field if it is present, and otherwise to the :mailheader:`From` field. |
Raymond Hettinger | 624e222 | 2016-08-30 13:25:06 -0700 | [diff] [blame] | 505 | *to_addrs* combines the values (if any) of the :mailheader:`To`, |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 506 | :mailheader:`Cc`, and :mailheader:`Bcc` fields from *msg*. If exactly one |
| 507 | set of :mailheader:`Resent-*` headers appear in the message, the regular |
| 508 | headers are ignored and the :mailheader:`Resent-*` headers are used instead. |
| 509 | If the message contains more than one set of :mailheader:`Resent-*` headers, |
| 510 | a :exc:`ValueError` is raised, since there is no way to unambiguously detect |
| 511 | the most recent set of :mailheader:`Resent-` headers. |
| 512 | |
| 513 | ``send_message`` serializes *msg* using |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 514 | :class:`~email.generator.BytesGenerator` with ``\r\n`` as the *linesep*, and |
R David Murray | ac4e5ab | 2011-07-02 21:03:19 -0400 | [diff] [blame] | 515 | calls :meth:`sendmail` to transmit the resulting message. Regardless of the |
| 516 | values of *from_addr* and *to_addrs*, ``send_message`` does not transmit any |
| 517 | :mailheader:`Bcc` or :mailheader:`Resent-Bcc` headers that may appear |
R David Murray | 8308444 | 2015-05-17 19:27:22 -0400 | [diff] [blame] | 518 | in *msg*. If any of the addresses in *from_addr* and *to_addrs* contain |
| 519 | non-ASCII characters and the server does not advertise ``SMTPUTF8`` support, |
| 520 | an :exc:`SMTPNotSupported` error is raised. Otherwise the ``Message`` is |
| 521 | serialized with a clone of its :mod:`~email.policy` with the |
| 522 | :attr:`~email.policy.EmailPolicy.utf8` attribute set to ``True``, and |
| 523 | ``SMTPUTF8`` and ``BODY=8BITMIME`` are added to *mail_options*. |
R. David Murray | 7dff9e0 | 2010-11-08 17:15:13 +0000 | [diff] [blame] | 524 | |
| 525 | .. versionadded:: 3.2 |
| 526 | |
R David Murray | 8308444 | 2015-05-17 19:27:22 -0400 | [diff] [blame] | 527 | .. versionadded:: 3.5 |
| 528 | Support for internationalized addresses (``SMTPUTF8``). |
| 529 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 530 | |
| 531 | .. method:: SMTP.quit() |
| 532 | |
Christian Heimes | ba4af49 | 2008-03-28 00:55:15 +0000 | [diff] [blame] | 533 | Terminate the SMTP session and close the connection. Return the result of |
| 534 | the SMTP ``QUIT`` command. |
| 535 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 536 | |
| 537 | Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``, |
| 538 | ``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported. |
| 539 | Normally these do not need to be called directly, so they are not documented |
| 540 | here. For details, consult the module code. |
| 541 | |
| 542 | |
| 543 | .. _smtp-example: |
| 544 | |
| 545 | SMTP Example |
| 546 | ------------ |
| 547 | |
| 548 | This example prompts the user for addresses needed in the message envelope ('To' |
| 549 | and 'From' addresses), and the message to be delivered. Note that the headers |
| 550 | to be included with the message must be included in the message as entered; this |
| 551 | example doesn't do any processing of the :rfc:`822` headers. In particular, the |
| 552 | 'To' and 'From' addresses must be included in the message headers explicitly. :: |
| 553 | |
| 554 | import smtplib |
| 555 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 556 | def prompt(prompt): |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 557 | return input(prompt).strip() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 558 | |
| 559 | fromaddr = prompt("From: ") |
| 560 | toaddrs = prompt("To: ").split() |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 561 | print("Enter message, end with ^D (Unix) or ^Z (Windows):") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 562 | |
| 563 | # Add the From: and To: headers at the start! |
| 564 | msg = ("From: %s\r\nTo: %s\r\n\r\n" |
| 565 | % (fromaddr, ", ".join(toaddrs))) |
Collin Winter | 4633448 | 2007-09-10 00:49:57 +0000 | [diff] [blame] | 566 | while True: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 567 | try: |
Georg Brandl | 8d5c392 | 2007-12-02 22:48:17 +0000 | [diff] [blame] | 568 | line = input() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 569 | except EOFError: |
| 570 | break |
| 571 | if not line: |
| 572 | break |
| 573 | msg = msg + line |
| 574 | |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 575 | print("Message length is", len(msg)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 576 | |
| 577 | server = smtplib.SMTP('localhost') |
| 578 | server.set_debuglevel(1) |
| 579 | server.sendmail(fromaddr, toaddrs, msg) |
| 580 | server.quit() |
| 581 | |
Benjamin Peterson | fa0d703 | 2009-06-01 22:42:33 +0000 | [diff] [blame] | 582 | .. note:: |
| 583 | |
| 584 | 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] | 585 | construct an email message, which you can then send |
| 586 | via :meth:`~smtplib.SMTP.send_message`; see :ref:`email-examples`. |