rest25/library/smtplib.rst => rest262/library/smtplib.rst
12   single: Simple Mail Transfer Protocol
13
14The :mod:`smtplib` module defines an SMTP client session object that can be used
15to send mail to any Internet machine with an SMTP or ESMTP listener daemon.  For
16details of SMTP and ESMTP operation, consult :rfc:`821` (Simple Mail Transfer
17Protocol) and :rfc:`1869` (SMTP Service Extensions).
18
19
n20-.. class:: SMTP([host[, port[, local_hostname]]])
n20+.. class:: SMTP([host[, port[, local_hostname[, timeout]]]])
21
n22-   A :class:`SMTP` instance encapsulates an SMTP connection.  It has methods that
n22+   A :class:`SMTP` instance encapsulates an SMTP connection.  It has methods
23-   support a full repertoire of SMTP and ESMTP operations. If the optional host and
23+   that support a full repertoire of SMTP and ESMTP operations. If the optional
24-   port parameters are given, the SMTP :meth:`connect` method is called with those
24+   host and port parameters are given, the SMTP :meth:`connect` method is called
25-   parameters during initialization.  An :exc:`SMTPConnectError` is raised if the
25+   with those parameters during initialization.  An :exc:`SMTPConnectError` is
26-   specified host doesn't respond correctly.
26+   raised if the specified host doesn't respond correctly. The optional
27+   *timeout* parameter specifies a timeout in seconds for blocking operations
28+   like the connection attempt (if not specified, the global default timeout
29+   setting will be used).
27
28   For normal use, you should only require the initialization/connect,
29   :meth:`sendmail`, and :meth:`quit` methods.  An example is included below.
n33+ 
34+   .. versionchanged:: 2.6
35+      *timeout* was added.
36+ 
37+ 
38+.. class:: SMTP_SSL([host[, port[, local_hostname[, keyfile[, certfile[, timeout]]]]]])
39+ 
40+   A :class:`SMTP_SSL` instance behaves exactly the same as instances of
41+   :class:`SMTP`. :class:`SMTP_SSL` should be used for situations where SSL is
42+   required from the beginning of the connection and using :meth:`starttls` is
43+   not appropriate. If *host* is not specified, the local host is used. If
44+   *port* is omitted, the standard SMTP-over-SSL port (465) is used. *keyfile*
45+   and *certfile* are also optional, and can contain a PEM formatted private key
46+   and certificate chain file for the SSL connection. The optional *timeout*
47+   parameter specifies a timeout in seconds for blocking operations like the
48+   connection attempt (if not specified, the global default timeout setting
49+   will be used).
50+ 
51+   .. versionchanged:: 2.6
52+      *timeout* was added.
53+ 
54+ 
55+.. class:: LMTP([host[, port[, local_hostname]]])
56+ 
57+   The LMTP protocol, which is very similar to ESMTP, is heavily based on the
58+   standard SMTP client. It's common to use Unix sockets for LMTP, so our :meth:`connect`
59+   method must support that as well as a regular host:port server. To specify a
60+   Unix socket, you must use an absolute path for *host*, starting with a '/'.
61+ 
62+   Authentication is supported, using the regular SMTP mechanism. When using a Unix
63+   socket, LMTP generally don't support or require any authentication, but your
64+   mileage might vary.
65+ 
66+   .. versionadded:: 2.6
30
31A nice selection of exceptions is defined as well:
32
33
34.. exception:: SMTPException
35
36   Base exception class for all exceptions raised by this module.
37
75   Error occurred during establishment of a connection  with the server.
76
77
78.. exception:: SMTPHeloError
79
80   The server refused our ``HELO`` message.
81
82
n120+.. exception:: SMTPAuthenticationError
121+ 
122+   SMTP authentication went wrong.  Most probably the server didn't accept the
123+   username/password combination provided.
124+ 
125+ 
83.. seealso::
84
85   :rfc:`821` - Simple Mail Transfer Protocol
86      Protocol definition for SMTP.  This document covers the model, operating
87      procedure, and protocol details for SMTP.
88
89   :rfc:`1869` - SMTP Service Extensions
90      Definition of the ESMTP extensions for SMTP.  This describes a framework for
95.. _smtp-objects:
96
97SMTP Objects
98------------
99
100An :class:`SMTP` instance has the following methods:
101
102
n103-.. method:: XXX Class.set_debuglevel(level)
n146+.. method:: SMTP.set_debuglevel(level)
104
105   Set the debug output level.  A true value for *level* results in debug messages
106   for connection and for all messages sent to and received from the server.
107
108
n109-.. method:: XXX Class.connect([host[, port]])
n152+.. method:: SMTP.connect([host[, port]])
110
111   Connect to a host on a given port.  The defaults are to connect to the local
112   host at the standard SMTP port (25). If the hostname ends with a colon (``':'``)
113   followed by a number, that suffix will be stripped off and the number
114   interpreted as the port number to use. This method is automatically invoked by
115   the constructor if a host is specified during instantiation.
116
117
n118-.. method:: XXX Class.docmd(cmd, [, argstring])
n161+.. method:: SMTP.docmd(cmd, [, argstring])
119
120   Send a command *cmd* to the server.  The optional argument *argstring* is simply
121   concatenated to the command, separated by a space.
122
123   This returns a 2-tuple composed of a numeric response code and the actual
124   response line (multiline responses are joined into one long line.)
125
126   In normal operation it should not be necessary to call this method explicitly.
127   It is used to implement other methods and may be useful for testing private
128   extensions.
129
130   If the connection to the server is lost while waiting for the reply,
131   :exc:`SMTPServerDisconnected` will be raised.
132
133
n134-.. method:: XXX Class.helo([hostname])
n177+.. method:: SMTP.helo([hostname])
135
136   Identify yourself to the SMTP server using ``HELO``.  The hostname argument
137   defaults to the fully qualified domain name of the local host.
n181+   The message returned by the server is stored as the :attr:`helo_resp` attribute
182+   of the object.
138
139   In normal operation it should not be necessary to call this method explicitly.
140   It will be implicitly called by the :meth:`sendmail` when necessary.
141
142
n143-.. method:: XXX Class.ehlo([hostname])
n188+.. method:: SMTP.ehlo([hostname])
144
145   Identify yourself to an ESMTP server using ``EHLO``.  The hostname argument
146   defaults to the fully qualified domain name of the local host.  Examine the
147   response for ESMTP option and store them for use by :meth:`has_extn`.
n193+   Also sets several informational attributes: the message returned by
194+   the server is stored as the :attr:`ehlo_resp` attribute, :attr:`does_esmtp`
195+   is set to true or false depending on whether the server supports ESMTP, and
196+   :attr:`esmtp_features` will be a dictionary containing the names of the
197+   SMTP service extensions this server supports, and their
198+   parameters (if any).
148
149   Unless you wish to use :meth:`has_extn` before sending mail, it should not be
150   necessary to call this method explicitly.  It will be implicitly called by
151   :meth:`sendmail` when necessary.
152
n204+.. method:: SMTP.ehlo_or_helo_if_needed()
153
n206+   This method call :meth:`ehlo` and or :meth:`helo` if there has been no
207+   previous ``EHLO`` or ``HELO`` command this session.  It tries ESMTP ``EHLO``
208+   first.
209+ 
210+   :exc:`SMTPHeloError`
211+     The server didn't reply properly to the ``HELO`` greeting.
212+ 
213+   .. versionadded:: 2.6
214+ 
154-.. method:: XXX Class.has_extn(name)
215+.. method:: SMTP.has_extn(name)
155
156   Return :const:`True` if *name* is in the set of SMTP service extensions returned
157   by the server, :const:`False` otherwise. Case is ignored.
158
159
n160-.. method:: XXX Class.verify(address)
n221+.. method:: SMTP.verify(address)
161
162   Check the validity of an address on this server using SMTP ``VRFY``. Returns a
163   tuple consisting of code 250 and a full :rfc:`822` address (including human
164   name) if the user address is valid. Otherwise returns an SMTP error code of 400
165   or greater and an error string.
166
167   .. note::
168
169      Many sites disable SMTP ``VRFY`` in order to foil spammers.
170
171
n172-.. method:: XXX Class.login(user, password)
n233+.. method:: SMTP.login(user, password)
173
174   Log in on an SMTP server that requires authentication. The arguments are the
175   username and the password to authenticate with. If there has been no previous
176   ``EHLO`` or ``HELO`` command this session, this method tries ESMTP ``EHLO``
177   first. This method will return normally if the authentication was successful, or
178   may raise the following exceptions:
179
180   :exc:`SMTPHeloError`
181      The server didn't reply properly to the ``HELO`` greeting.
182
183   :exc:`SMTPAuthenticationError`
184      The server didn't accept the username/password combination.
185
n186-   :exc:`SMTPError`
n247+   :exc:`SMTPException`
187      No suitable authentication method was found.
188
189
n190-.. method:: XXX Class.starttls([keyfile[, certfile]])
n251+.. method:: SMTP.starttls([keyfile[, certfile]])
191
192   Put the SMTP connection in TLS (Transport Layer Security) mode.  All SMTP
193   commands that follow will be encrypted.  You should then call :meth:`ehlo`
194   again.
195
196   If *keyfile* and *certfile* are provided, these are passed to the :mod:`socket`
197   module's :func:`ssl` function.
198
n260+   If there has been no previous ``EHLO`` or ``HELO`` command this session,
261+   this method tries ESMTP ``EHLO`` first.
199
n263+   .. versionchanged:: 2.6
264+ 
265+   :exc:`SMTPHeloError`
266+      The server didn't reply properly to the ``HELO`` greeting.
267+ 
268+   :exc:`SMTPException`
269+     The server does not support the STARTTLS extension.
270+ 
271+   .. versionchanged:: 2.6
272+ 
273+   :exc:`RuntimeError`
274+     SSL/TLS support is not available to your python interpreter.
275+ 
276+ 
200-.. method:: XXX Class.sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])
277+.. method:: SMTP.sendmail(from_addr, to_addrs, msg[, mail_options, rcpt_options])
201
202   Send mail.  The required arguments are an :rfc:`822` from-address string, a list
203   of :rfc:`822` to-address strings (a bare string will be treated as a list with 1
204   address), and a message string.  The caller may pass a list of ESMTP options
205   (such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options*.
206   ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT``
207   commands can be passed as *rcpt_options*.  (If you need to use different ESMTP
208   options to different recipients you have to use the low-level methods such as
244   :exc:`SMTPDataError`
245      The server replied with an unexpected error code (other than a refusal of a
246      recipient).
247
248   Unless otherwise noted, the connection will be open even after an exception is
249   raised.
250
251
n252-.. method:: XXX Class.quit()
n329+.. method:: SMTP.quit()
253
t254-   Terminate the SMTP session and close the connection.
t331+   Terminate the SMTP session and close the connection.  Return the result of
332+   the SMTP ``QUIT`` command.
333+ 
334+   .. versionchanged:: 2.6
335+      Return a value.
336+ 
255
256Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``,
257``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported.
258Normally these do not need to be called directly, so they are not documented
259here.  For details, consult the module code.
260
261
262.. _smtp-example:
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op