Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(182973)

Delta Between Two Patch Sets: Doc/library/smtplib.rst

Issue 10321: Add support for Message objects and binary data to smtplib.sendmail
Left Patch Set: Created 8 years, 8 months ago
Right Patch Set: Created 8 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « Doc/includes/email-simple.py ('k') | Doc/whatsnew/3.2.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`smtplib` --- SMTP protocol client 1 :mod:`smtplib` --- SMTP protocol client
2 ======================================= 2 =======================================
3 3
4 .. module:: smtplib 4 .. module:: smtplib
5 :synopsis: SMTP protocol client (requires sockets). 5 :synopsis: SMTP protocol client (requires sockets).
6 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> 6 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
7 7
8 8
9 .. index:: 9 .. index::
10 pair: SMTP; protocol 10 pair: SMTP; protocol
(...skipping 246 matching lines...) Expand 10 before | Expand all | Expand 10 after
257 The server does not support the STARTTLS extension. 257 The server does not support the STARTTLS extension.
258 258
259 :exc:`RuntimeError` 259 :exc:`RuntimeError`
260 SSL/TLS support is not available to your Python interpreter. 260 SSL/TLS support is not available to your Python interpreter.
261 261
262 262
263 .. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_option s=[]) 263 .. method:: SMTP.sendmail(from_addr, to_addrs, msg, mail_options=[], rcpt_option s=[])
264 264
265 Send mail. The required arguments are an :rfc:`822` from-address string, a l ist 265 Send mail. The required arguments are an :rfc:`822` from-address string, a l ist
266 of :rfc:`822` to-address strings (a bare string will be treated as a list wit h 1 266 of :rfc:`822` to-address strings (a bare string will be treated as a list wit h 1
267 address), and a message. The caller may pass a list of ESMTP options 267 address), and a message string. The caller may pass a list of ESMTP options
268 (such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options* . 268 (such as ``8bitmime``) to be used in ``MAIL FROM`` commands as *mail_options* .
269 ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT` ` 269 ESMTP options (such as ``DSN`` commands) that should be used with all ``RCPT` `
270 commands can be passed as *rcpt_options*. (If you need to use different ESMT P 270 commands can be passed as *rcpt_options*. (If you need to use different ESMT P
271 options to different recipients you have to use the low-level methods such as 271 options to different recipients you have to use the low-level methods such as
272 :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.) 272 :meth:`mail`, :meth:`rcpt` and :meth:`data` to send the message.)
273 273
274 .. note:: 274 .. note::
275 275
276 The *from_addr* and *to_addrs* parameters are used to construct the messag e 276 The *from_addr* and *to_addrs* parameters are used to construct the messag e
277 envelope used by the transport agents. The :class:`SMTP` does not modify t he 277 envelope used by the transport agents. ``sendmail`` does not modify the
278 message headers in any way, with the sole exception of the :mailheader:`Bc c` 278 message headers in any way.
279 field if *msg* is a :class:`~email.message.Message` object.
280 279
281 msg may be a string containing characters in the ASCII range, or a byte 280 msg may be a string containing characters in the ASCII range, or a byte
282 string, or a :class:`~email.message.Message` object. A string is encoded to 281 string. A string is encoded to bytes using the ascii codec, and lone ``\r``
283 bytes using the ascii codec, and lone ``\r`` and ``\n`` characters are 282 and ``\n`` characters are converted to ``\r\n`` characters. A byte string
284 converted to ``\r\n`` characters. A byte string is transmitted as is. A 283 is not modified.
285 Message object is serialized using :class:`~email.generator.BytesGenerator`.
286
287 When msg is a Message object, *from_addr* and *to_addrs* may be set to
288 ``None``, in which case the *from_addr* is taken from the :mailheader:`From`
289 header of the Message, and *to_addrs* is composed from the addresses listed
290 in the :mailheader:`To`, :mailheader:`CC`, and :mailheader:`Bcc` fields.
291 Regardless, any Bcc field in the ``Message`` object is deleted before it is
292 serialized.
293
294 .. note::
295
296 The :mailheader:`Bcc` header is removed *only* when *msg* is a
297 :class:`~email.message.Message` object.
298
299 If there has been no previous EHLO or HELO command this session, this method
300 tries ESMTP EHLO first. If the server does ESMTP, message size and each of
301 the specified options will be passed to it. If EHLO fails, HELO will be
302 tried and ESMTP options suppressed.
303 284
304 If there has been no previous ``EHLO`` or ``HELO`` command this session, this 285 If there has been no previous ``EHLO`` or ``HELO`` command this session, this
305 method tries ESMTP ``EHLO`` first. If the server does ESMTP, message size and 286 method tries ESMTP ``EHLO`` first. If the server does ESMTP, message size and
306 each of the specified options will be passed to it (if the option is in the 287 each of the specified options will be passed to it (if the option is in the
307 feature set the server advertises). If ``EHLO`` fails, ``HELO`` will be trie d 288 feature set the server advertises). If ``EHLO`` fails, ``HELO`` will be trie d
308 and ESMTP options suppressed. 289 and ESMTP options suppressed.
309 290
310 This method will return normally if the mail is accepted for at least one 291 This method will return normally if the mail is accepted for at least one
311 recipient. Otherwise it will raise an exception. That is, if this method doe s 292 recipient. Otherwise it will raise an exception. That is, if this method doe s
312 not raise an exception, then someone should get your mail. If this method doe s 293 not raise an exception, then someone should get your mail. If this method doe s
(...skipping 14 matching lines...) Expand all
327 308
328 :exc:`SMTPSenderRefused` 309 :exc:`SMTPSenderRefused`
329 The server didn't accept the *from_addr*. 310 The server didn't accept the *from_addr*.
330 311
331 :exc:`SMTPDataError` 312 :exc:`SMTPDataError`
332 The server replied with an unexpected error code (other than a refusal of a 313 The server replied with an unexpected error code (other than a refusal of a
333 recipient). 314 recipient).
334 315
335 Unless otherwise noted, the connection will be open even after an exception i s 316 Unless otherwise noted, the connection will be open even after an exception i s
336 raised. 317 raised.
318
319 .. versionchanged:: 3.2 *msg* may be a byte string.
320
321
322 .. method:: SMTP.send_message(msg, from_addr=None, to_addrs=None, mail_options=[ ], rcpt_options=[])
323
324 This is a convenience method for calling :meth:`sendmail` with the message
325 represented by an :class:`email.message.Message` object. The arguments have
326 the same meaning as for :meth:`sendmail`, except that *msg* is a ``Message``
327 object.
328
329 If *from_addr* is ``None``, ``send_message`` sets its value to the value of
330 the :mailheader:`From` header from *msg*. If *to_addrs* is ``None``,
331 ``send_message`` combines the values (if any) of the :mailheader:`To`,
332 :mailheader:`CC`, and :mailheader:`Bcc` fields from *msg*. Regardless of
333 the values of *from_addr* and *to_addrs*, ``send_message`` deletes any Bcc
334 field from *msg*. It then serializes *msg* using
335 :class:`~email.generator.BytesGenerator` with ``\r\n`` as the *linesep*, and
336 calls :meth:`sendmail` to transmit the resulting message.
337
338 .. versionadded:: 3.2
337 339
338 340
339 .. method:: SMTP.quit() 341 .. method:: SMTP.quit()
340 342
341 Terminate the SMTP session and close the connection. Return the result of 343 Terminate the SMTP session and close the connection. Return the result of
342 the SMTP ``QUIT`` command. 344 the SMTP ``QUIT`` command.
343 345
344 346
345 Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``, 347 Low-level methods corresponding to the standard SMTP/ESMTP commands ``HELP``,
346 ``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported. 348 ``RSET``, ``NOOP``, ``MAIL``, ``RCPT``, and ``DATA`` are also supported.
(...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after
384 386
385 server = smtplib.SMTP('localhost') 387 server = smtplib.SMTP('localhost')
386 server.set_debuglevel(1) 388 server.set_debuglevel(1)
387 server.sendmail(fromaddr, toaddrs, msg) 389 server.sendmail(fromaddr, toaddrs, msg)
388 server.quit() 390 server.quit()
389 391
390 .. note:: 392 .. note::
391 393
392 In general, you will want to use the :mod:`email` package's features to 394 In general, you will want to use the :mod:`email` package's features to
393 construct an email message, which you can then send 395 construct an email message, which you can then send
394 via :meth:`~smtplib.SMTP.sendmail`; see :ref:`email-examples`. 396 via :meth:`~smtplib.SMTP.send_message`; see :ref:`email-examples`.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+