931 lines
86 KiB
HTML
931 lines
86 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>email.message: Representing an email message — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="email.parser: Parsing email messages" href="email.parser.html" />
|
|||
|
|
<link rel="prev" title="email — An email and MIME handling package" href="email.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/email.message.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.parser.html" title="email.parser: Parsing email messages"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.html" title="email — An email and MIME handling package"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-3"><a href="email.html" accesskey="U"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> — An email and MIME handling package</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="module-email.message">
|
|||
|
|
<span id="email-message-representing-an-email-message"></span><h1><a class="reference internal" href="#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code></a>: Representing an email message<a class="headerlink" href="#module-email.message" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/email/message.py">Lib/email/message.py</a></p>
|
|||
|
|
<hr class="docutils" />
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.6: </span><a class="footnote-reference brackets" href="#id2" id="id1">1</a></p>
|
|||
|
|
</div>
|
|||
|
|
<p>The central class in the <a class="reference internal" href="email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code></a> package is the <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>
|
|||
|
|
class, imported from the <a class="reference internal" href="#module-email.message" title="email.message: The base class representing email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code></a> module. It is the base class for
|
|||
|
|
the <a class="reference internal" href="email.html#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code></a> object model. <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> provides the core
|
|||
|
|
functionality for setting and querying header fields, for accessing message
|
|||
|
|
bodies, and for creating or modifying structured messages.</p>
|
|||
|
|
<p>An email message consists of <em>headers</em> and a <em>payload</em> (which is also referred
|
|||
|
|
to as the <em>content</em>). Headers are <span class="target" id="index-0"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc5322.html"><strong>RFC 5322</strong></a> or <span class="target" id="index-1"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc6532.html"><strong>RFC 6532</strong></a> style field names
|
|||
|
|
and values, where the field name and value are separated by a colon. The colon
|
|||
|
|
is not part of either the field name or the field value. The payload may be a
|
|||
|
|
simple text message, or a binary object, or a structured sequence of
|
|||
|
|
sub-messages each with their own set of headers and their own payload. The
|
|||
|
|
latter type of payload is indicated by the message having a MIME type such as
|
|||
|
|
<em class="mimetype">multipart/*</em> or <em class="mimetype">message/rfc822</em>.</p>
|
|||
|
|
<p>The conceptual model provided by an <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> object is that of an
|
|||
|
|
ordered dictionary of headers coupled with a <em>payload</em> that represents the
|
|||
|
|
<span class="target" id="index-2"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc5322.html"><strong>RFC 5322</strong></a> body of the message, which might be a list of sub-<code class="docutils literal notranslate"><span class="pre">EmailMessage</span></code>
|
|||
|
|
objects. In addition to the normal dictionary methods for accessing the header
|
|||
|
|
names and values, there are methods for accessing specialized information from
|
|||
|
|
the headers (for example the MIME content type), for operating on the payload,
|
|||
|
|
for generating a serialized version of the message, and for recursively walking
|
|||
|
|
over the object tree.</p>
|
|||
|
|
<p>The <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> dictionary-like interface is indexed by the header
|
|||
|
|
names, which must be ASCII values. The values of the dictionary are strings
|
|||
|
|
with some extra methods. Headers are stored and returned in case-preserving
|
|||
|
|
form, but field names are matched case-insensitively. Unlike a real dict,
|
|||
|
|
there is an ordering to the keys, and there can be duplicate keys. Additional
|
|||
|
|
methods are provided for working with headers that have duplicate keys.</p>
|
|||
|
|
<p>The <em>payload</em> is either a string or bytes object, in the case of simple message
|
|||
|
|
objects, or a list of <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> objects, for MIME container
|
|||
|
|
documents such as <em class="mimetype">multipart/*</em> and <em class="mimetype">message/rfc822</em>
|
|||
|
|
message objects.</p>
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="email.message.EmailMessage">
|
|||
|
|
<em class="property">class </em><code class="descclassname">email.message.</code><code class="descname">EmailMessage</code><span class="sig-paren">(</span><em>policy=default</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If <em>policy</em> is specified use the rules it specifies to update and serialize
|
|||
|
|
the representation of the message. If <em>policy</em> is not set, use the
|
|||
|
|
<a class="reference internal" href="email.policy.html#email.policy.default" title="email.policy.default"><code class="xref py py-class docutils literal notranslate"><span class="pre">default</span></code></a> policy, which follows the rules of the email
|
|||
|
|
RFCs except for line endings (instead of the RFC mandated <code class="docutils literal notranslate"><span class="pre">\r\n</span></code>, it uses
|
|||
|
|
the Python standard <code class="docutils literal notranslate"><span class="pre">\n</span></code> line endings). For more information see the
|
|||
|
|
<a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a> documentation.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.as_string">
|
|||
|
|
<code class="descname">as_string</code><span class="sig-paren">(</span><em>unixfrom=False</em>, <em>maxheaderlen=None</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.as_string" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the entire message flattened as a string. When optional
|
|||
|
|
<em>unixfrom</em> is true, the envelope header is included in the returned
|
|||
|
|
string. <em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. For backward compatibility
|
|||
|
|
with the base <a class="reference internal" href="email.compat32-message.html#email.message.Message" title="email.message.Message"><code class="xref py py-class docutils literal notranslate"><span class="pre">Message</span></code></a> class <em>maxheaderlen</em> is
|
|||
|
|
accepted, but defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, which means that by default the line
|
|||
|
|
length is controlled by the
|
|||
|
|
<code class="xref py py-attr docutils literal notranslate"><span class="pre">max_line_length</span></code> of the policy. The
|
|||
|
|
<em>policy</em> argument may be used to override the default policy obtained
|
|||
|
|
from the message instance. This can be used to control some of the
|
|||
|
|
formatting produced by the method, since the specified <em>policy</em> will be
|
|||
|
|
passed to the <a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a>.</p>
|
|||
|
|
<p>Flattening the message may trigger changes to the <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>
|
|||
|
|
if defaults need to be filled in to complete the transformation to a
|
|||
|
|
string (for example, MIME boundaries may be generated or modified).</p>
|
|||
|
|
<p>Note that this method is provided as a convenience and may not be the
|
|||
|
|
most useful way to serialize messages in your application, especially if
|
|||
|
|
you are dealing with multiple messages. See
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.generator.Generator</span></code></a> for a more flexible API for
|
|||
|
|
serializing messages. Note also that this method is restricted to
|
|||
|
|
producing messages serialized as “7 bit clean” when
|
|||
|
|
<a class="reference internal" href="email.policy.html#email.policy.EmailPolicy.utf8" title="email.policy.EmailPolicy.utf8"><code class="xref py py-attr docutils literal notranslate"><span class="pre">utf8</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, which is the default.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.6: </span>the default behavior when <em>maxheaderlen</em>
|
|||
|
|
is not specified was changed from defaulting to 0 to defaulting
|
|||
|
|
to the value of <em>max_line_length</em> from the policy.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__str__">
|
|||
|
|
<code class="descname">__str__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__str__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">as_string(policy=self.policy.clone(utf8=True))</span></code>. Allows
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">str(msg)</span></code> to produce a string containing the serialized message in a
|
|||
|
|
readable format.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span>the method was changed to use <code class="docutils literal notranslate"><span class="pre">utf8=True</span></code>,
|
|||
|
|
thus producing an <span class="target" id="index-3"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc6531.html"><strong>RFC 6531</strong></a>-like message representation, instead of
|
|||
|
|
being a direct alias for <a class="reference internal" href="#email.message.EmailMessage.as_string" title="email.message.EmailMessage.as_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_string()</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.as_bytes">
|
|||
|
|
<code class="descname">as_bytes</code><span class="sig-paren">(</span><em>unixfrom=False</em>, <em>policy=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.as_bytes" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the entire message flattened as a bytes object. When optional
|
|||
|
|
<em>unixfrom</em> is true, the envelope header is included in the returned
|
|||
|
|
string. <em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>. The <em>policy</em> argument may be
|
|||
|
|
used to override the default policy obtained from the message instance.
|
|||
|
|
This can be used to control some of the formatting produced by the
|
|||
|
|
method, since the specified <em>policy</em> will be passed to the
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesGenerator</span></code></a>.</p>
|
|||
|
|
<p>Flattening the message may trigger changes to the <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>
|
|||
|
|
if defaults need to be filled in to complete the transformation to a
|
|||
|
|
string (for example, MIME boundaries may be generated or modified).</p>
|
|||
|
|
<p>Note that this method is provided as a convenience and may not be the
|
|||
|
|
most useful way to serialize messages in your application, especially if
|
|||
|
|
you are dealing with multiple messages. See
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.BytesGenerator" title="email.generator.BytesGenerator"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.generator.BytesGenerator</span></code></a> for a more flexible API for
|
|||
|
|
serializing messages.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__bytes__">
|
|||
|
|
<code class="descname">__bytes__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__bytes__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Equivalent to <a class="reference internal" href="#email.message.EmailMessage.as_bytes" title="email.message.EmailMessage.as_bytes"><code class="xref py py-meth docutils literal notranslate"><span class="pre">as_bytes()</span></code></a>. Allows <code class="docutils literal notranslate"><span class="pre">bytes(msg)</span></code> to produce a
|
|||
|
|
bytes object containing the serialized message.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.is_multipart">
|
|||
|
|
<code class="descname">is_multipart</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.is_multipart" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the message’s payload is a list of
|
|||
|
|
sub-<a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> objects, otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>. When
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, the payload should be a string
|
|||
|
|
object (which might be a CTE encoded binary payload). Note that
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returning <code class="docutils literal notranslate"><span class="pre">True</span></code> does not necessarily mean that
|
|||
|
|
“msg.get_content_maintype() == ‘multipart’” will return the <code class="docutils literal notranslate"><span class="pre">True</span></code>.
|
|||
|
|
For example, <code class="docutils literal notranslate"><span class="pre">is_multipart</span></code> will return <code class="docutils literal notranslate"><span class="pre">True</span></code> when the
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> is of type <code class="docutils literal notranslate"><span class="pre">message/rfc822</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.set_unixfrom">
|
|||
|
|
<code class="descname">set_unixfrom</code><span class="sig-paren">(</span><em>unixfrom</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_unixfrom" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the message’s envelope header to <em>unixfrom</em>, which should be a
|
|||
|
|
string. (See <a class="reference internal" href="mailbox.html#mailbox.mboxMessage" title="mailbox.mboxMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">mboxMessage</span></code></a> for a brief description of
|
|||
|
|
this header.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_unixfrom">
|
|||
|
|
<code class="descname">get_unixfrom</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_unixfrom" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s envelope header. Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> if the
|
|||
|
|
envelope header was never set.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following methods implement the mapping-like interface for accessing the
|
|||
|
|
message’s headers. Note that there are some semantic differences
|
|||
|
|
between these methods and a normal mapping (i.e. dictionary) interface. For
|
|||
|
|
example, in a dictionary there are no duplicate keys, but here there may be
|
|||
|
|
duplicate message headers. Also, in dictionaries there is no guaranteed
|
|||
|
|
order to the keys returned by <a class="reference internal" href="#email.message.EmailMessage.keys" title="email.message.EmailMessage.keys"><code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code></a>, but in an <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>
|
|||
|
|
object, headers are always returned in the order they appeared in the
|
|||
|
|
original message, or in which they were added to the message later. Any
|
|||
|
|
header deleted and then re-added is always appended to the end of the
|
|||
|
|
header list.</p>
|
|||
|
|
<p>These semantic differences are intentional and are biased toward
|
|||
|
|
convenience in the most common use cases.</p>
|
|||
|
|
<p>Note that in all cases, any envelope header present in the message is not
|
|||
|
|
included in the mapping interface.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__len__">
|
|||
|
|
<code class="descname">__len__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__len__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the total number of headers, including duplicates.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__contains__">
|
|||
|
|
<code class="descname">__contains__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__contains__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return true if the message object has a field named <em>name</em>. Matching is
|
|||
|
|
done without regard to case and <em>name</em> does not include the trailing
|
|||
|
|
colon. Used for the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator. For example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="s1">'message-id'</span> <span class="ow">in</span> <span class="n">myMessage</span><span class="p">:</span>
|
|||
|
|
<span class="nb">print</span><span class="p">(</span><span class="s1">'Message-ID:'</span><span class="p">,</span> <span class="n">myMessage</span><span class="p">[</span><span class="s1">'message-id'</span><span class="p">])</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__getitem__">
|
|||
|
|
<code class="descname">__getitem__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__getitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the named header field. <em>name</em> does not include the
|
|||
|
|
colon field separator. If the header is missing, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned; a
|
|||
|
|
<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is never raised.</p>
|
|||
|
|
<p>Note that if the named field appears more than once in the message’s
|
|||
|
|
headers, exactly which of those field values will be returned is
|
|||
|
|
undefined. Use the <a class="reference internal" href="#email.message.EmailMessage.get_all" title="email.message.EmailMessage.get_all"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_all()</span></code></a> method to get the values of all the
|
|||
|
|
extant headers named <em>name</em>.</p>
|
|||
|
|
<p>Using the standard (non-<code class="docutils literal notranslate"><span class="pre">compat32</span></code>) policies, the returned value is an
|
|||
|
|
instance of a subclass of <a class="reference internal" href="email.headerregistry.html#email.headerregistry.BaseHeader" title="email.headerregistry.BaseHeader"><code class="xref py py-class docutils literal notranslate"><span class="pre">email.headerregistry.BaseHeader</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__setitem__">
|
|||
|
|
<code class="descname">__setitem__</code><span class="sig-paren">(</span><em>name</em>, <em>val</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__setitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Add a header to the message with field name <em>name</em> and value <em>val</em>. The
|
|||
|
|
field is appended to the end of the message’s existing headers.</p>
|
|||
|
|
<p>Note that this does <em>not</em> overwrite or delete any existing header with the same
|
|||
|
|
name. If you want to ensure that the new header is the only one present in the
|
|||
|
|
message with field name <em>name</em>, delete the field first, e.g.:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">del</span> <span class="n">msg</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span>
|
|||
|
|
<span class="n">msg</span><span class="p">[</span><span class="s1">'subject'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'Python roolz!'</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>If the <code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code> defines certain headers to be unique (as the standard
|
|||
|
|
policies do), this method may raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> when an attempt
|
|||
|
|
is made to assign a value to such a header when one already exists. This
|
|||
|
|
behavior is intentional for consistency’s sake, but do not depend on it
|
|||
|
|
as we may choose to make such assignments do an automatic deletion of the
|
|||
|
|
existing header in the future.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.__delitem__">
|
|||
|
|
<code class="descname">__delitem__</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__delitem__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Delete all occurrences of the field with name <em>name</em> from the message’s
|
|||
|
|
headers. No exception is raised if the named field isn’t present in the
|
|||
|
|
headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.keys">
|
|||
|
|
<code class="descname">keys</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.keys" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the message’s header field names.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.values">
|
|||
|
|
<code class="descname">values</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.values" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the message’s field values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.items">
|
|||
|
|
<code class="descname">items</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.items" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of 2-tuples containing all the message’s field headers and
|
|||
|
|
values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get">
|
|||
|
|
<code class="descname">get</code><span class="sig-paren">(</span><em>name</em>, <em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the named header field. This is identical to
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.__getitem__" title="email.message.EmailMessage.__getitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__getitem__()</span></code></a> except that optional <em>failobj</em> is returned if the
|
|||
|
|
named header is missing (<em>failobj</em> defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>Here are some additional useful header related methods:</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_all">
|
|||
|
|
<code class="descname">get_all</code><span class="sig-paren">(</span><em>name</em>, <em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_all" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list of all the values for the field named <em>name</em>. If there are
|
|||
|
|
no such named headers in the message, <em>failobj</em> is returned (defaults to
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.add_header">
|
|||
|
|
<code class="descname">add_header</code><span class="sig-paren">(</span><em>_name</em>, <em>_value</em>, <em>**_params</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_header" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Extended header setting. This method is similar to <a class="reference internal" href="#email.message.EmailMessage.__setitem__" title="email.message.EmailMessage.__setitem__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__setitem__()</span></code></a>
|
|||
|
|
except that additional header parameters can be provided as keyword
|
|||
|
|
arguments. <em>_name</em> is the header field to add and <em>_value</em> is the
|
|||
|
|
<em>primary</em> value for the header.</p>
|
|||
|
|
<p>For each item in the keyword argument dictionary <em>_params</em>, the key is
|
|||
|
|
taken as the parameter name, with underscores converted to dashes (since
|
|||
|
|
dashes are illegal in Python identifiers). Normally, the parameter will
|
|||
|
|
be added as <code class="docutils literal notranslate"><span class="pre">key="value"</span></code> unless the value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case
|
|||
|
|
only the key will be added.</p>
|
|||
|
|
<p>If the value contains non-ASCII characters, the charset and language may
|
|||
|
|
be explicitly controlled by specifying the value as a three tuple in the
|
|||
|
|
format <code class="docutils literal notranslate"><span class="pre">(CHARSET,</span> <span class="pre">LANGUAGE,</span> <span class="pre">VALUE)</span></code>, where <code class="docutils literal notranslate"><span class="pre">CHARSET</span></code> is a string
|
|||
|
|
naming the charset to be used to encode the value, <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> can
|
|||
|
|
usually be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> or the empty string (see <span class="target" id="index-4"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> for other
|
|||
|
|
possibilities), and <code class="docutils literal notranslate"><span class="pre">VALUE</span></code> is the string value containing non-ASCII
|
|||
|
|
code points. If a three tuple is not passed and the value contains
|
|||
|
|
non-ASCII characters, it is automatically encoded in <span class="target" id="index-5"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> format
|
|||
|
|
using a <code class="docutils literal notranslate"><span class="pre">CHARSET</span></code> of <code class="docutils literal notranslate"><span class="pre">utf-8</span></code> and a <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
<p>Here is an example:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span><span class="o">.</span><span class="n">add_header</span><span class="p">(</span><span class="s1">'Content-Disposition'</span><span class="p">,</span> <span class="s1">'attachment'</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s1">'bud.gif'</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>This will add a header that looks like</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Content</span><span class="o">-</span><span class="n">Disposition</span><span class="p">:</span> <span class="n">attachment</span><span class="p">;</span> <span class="n">filename</span><span class="o">=</span><span class="s2">"bud.gif"</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>An example of the extended interface with non-ASCII characters:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span><span class="o">.</span><span class="n">add_header</span><span class="p">(</span><span class="s1">'Content-Disposition'</span><span class="p">,</span> <span class="s1">'attachment'</span><span class="p">,</span>
|
|||
|
|
<span class="n">filename</span><span class="o">=</span><span class="p">(</span><span class="s1">'iso-8859-1'</span><span class="p">,</span> <span class="s1">''</span><span class="p">,</span> <span class="s1">'Fußballer.ppt'</span><span class="p">))</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.replace_header">
|
|||
|
|
<code class="descname">replace_header</code><span class="sig-paren">(</span><em>_name</em>, <em>_value</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.replace_header" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Replace a header. Replace the first header found in the message that
|
|||
|
|
matches <em>_name</em>, retaining header order and field name case of the
|
|||
|
|
original header. If no matching header is found, raise a
|
|||
|
|
<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content_type">
|
|||
|
|
<code class="descname">get_content_type</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s content type, coerced to lower case of the form
|
|||
|
|
<em class="mimetype">maintype/subtype</em>. If there is no <em class="mailheader">Content-Type</em>
|
|||
|
|
header in the message return the value returned by
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.get_default_type" title="email.message.EmailMessage.get_default_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_default_type()</span></code></a>. If the <em class="mailheader">Content-Type</em> header is
|
|||
|
|
invalid, return <code class="docutils literal notranslate"><span class="pre">text/plain</span></code>.</p>
|
|||
|
|
<p>(According to <span class="target" id="index-6"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a>, messages always have a default type,
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.get_content_type" title="email.message.EmailMessage.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a> will always return a value. <span class="target" id="index-7"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a> defines
|
|||
|
|
a message’s default type to be <em class="mimetype">text/plain</em> unless it appears
|
|||
|
|
inside a <em class="mimetype">multipart/digest</em> container, in which case it would
|
|||
|
|
be <em class="mimetype">message/rfc822</em>. If the <em class="mailheader">Content-Type</em> header
|
|||
|
|
has an invalid type specification, <span class="target" id="index-8"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2045.html"><strong>RFC 2045</strong></a> mandates that the default
|
|||
|
|
type be <em class="mimetype">text/plain</em>.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content_maintype">
|
|||
|
|
<code class="descname">get_content_maintype</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_maintype" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s main content type. This is the <em class="mimetype">maintype</em>
|
|||
|
|
part of the string returned by <a class="reference internal" href="#email.message.EmailMessage.get_content_type" title="email.message.EmailMessage.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content_subtype">
|
|||
|
|
<code class="descname">get_content_subtype</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_subtype" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the message’s sub-content type. This is the <em class="mimetype">subtype</em>
|
|||
|
|
part of the string returned by <a class="reference internal" href="#email.message.EmailMessage.get_content_type" title="email.message.EmailMessage.get_content_type"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_default_type">
|
|||
|
|
<code class="descname">get_default_type</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_default_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the default content type. Most messages have a default content
|
|||
|
|
type of <em class="mimetype">text/plain</em>, except for messages that are subparts of
|
|||
|
|
<em class="mimetype">multipart/digest</em> containers. Such subparts have a default
|
|||
|
|
content type of <em class="mimetype">message/rfc822</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.set_default_type">
|
|||
|
|
<code class="descname">set_default_type</code><span class="sig-paren">(</span><em>ctype</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_default_type" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the default content type. <em>ctype</em> should either be
|
|||
|
|
<em class="mimetype">text/plain</em> or <em class="mimetype">message/rfc822</em>, although this is
|
|||
|
|
not enforced. The default content type is not stored in the
|
|||
|
|
<em class="mailheader">Content-Type</em> header, so it only affects the return value of
|
|||
|
|
the <code class="docutils literal notranslate"><span class="pre">get_content_type</span></code> methods when no <em class="mailheader">Content-Type</em>
|
|||
|
|
header is present in the message.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.set_param">
|
|||
|
|
<code class="descname">set_param</code><span class="sig-paren">(</span><em>param</em>, <em>value</em>, <em>header='Content-Type'</em>, <em>requote=True</em>, <em>charset=None</em>, <em>language=''</em>, <em>replace=False</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_param" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set a parameter in the <em class="mailheader">Content-Type</em> header. If the
|
|||
|
|
parameter already exists in the header, replace its value with <em>value</em>.
|
|||
|
|
When <em>header</em> is <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> (the default) and the header does not
|
|||
|
|
yet exist in the message, add it, set its value to
|
|||
|
|
<em class="mimetype">text/plain</em>, and append the new parameter value. Optional
|
|||
|
|
<em>header</em> specifies an alternative header to <em class="mailheader">Content-Type</em>.</p>
|
|||
|
|
<p>If the value contains non-ASCII characters, the charset and language may
|
|||
|
|
be explicitly specified using the optional <em>charset</em> and <em>language</em>
|
|||
|
|
parameters. Optional <em>language</em> specifies the <span class="target" id="index-9"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2231.html"><strong>RFC 2231</strong></a> language,
|
|||
|
|
defaulting to the empty string. Both <em>charset</em> and <em>language</em> should be
|
|||
|
|
strings. The default is to use the <code class="docutils literal notranslate"><span class="pre">utf8</span></code> <em>charset</em> and <code class="docutils literal notranslate"><span class="pre">None</span></code> for
|
|||
|
|
the <em>language</em>.</p>
|
|||
|
|
<p>If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default) the header is moved to the
|
|||
|
|
end of the list of headers. If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the header
|
|||
|
|
will be updated in place.</p>
|
|||
|
|
<p>Use of the <em>requote</em> parameter with <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> objects is
|
|||
|
|
deprecated.</p>
|
|||
|
|
<p>Note that existing parameter values of headers may be accessed through
|
|||
|
|
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">params</span></code> attribute of the
|
|||
|
|
header value (for example, <code class="docutils literal notranslate"><span class="pre">msg['Content-Type'].params['charset']</span></code>).</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4: </span><code class="docutils literal notranslate"><span class="pre">replace</span></code> keyword was added.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.del_param">
|
|||
|
|
<code class="descname">del_param</code><span class="sig-paren">(</span><em>param</em>, <em>header='content-type'</em>, <em>requote=True</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.del_param" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Remove the given parameter completely from the <em class="mailheader">Content-Type</em>
|
|||
|
|
header. The header will be re-written in place without the parameter or
|
|||
|
|
its value. Optional <em>header</em> specifies an alternative to
|
|||
|
|
<em class="mailheader">Content-Type</em>.</p>
|
|||
|
|
<p>Use of the <em>requote</em> parameter with <a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> objects is
|
|||
|
|
deprecated.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_filename">
|
|||
|
|
<code class="descname">get_filename</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_filename" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter of the
|
|||
|
|
<em class="mailheader">Content-Disposition</em> header of the message. If the header
|
|||
|
|
does not have a <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter, this method falls back to looking
|
|||
|
|
for the <code class="docutils literal notranslate"><span class="pre">name</span></code> parameter on the <em class="mailheader">Content-Type</em> header. If
|
|||
|
|
neither is found, or the header is missing, then <em>failobj</em> is returned.
|
|||
|
|
The returned string will always be unquoted as per
|
|||
|
|
<a class="reference internal" href="email.utils.html#email.utils.unquote" title="email.utils.unquote"><code class="xref py py-func docutils literal notranslate"><span class="pre">email.utils.unquote()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_boundary">
|
|||
|
|
<code class="descname">get_boundary</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_boundary" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter of the
|
|||
|
|
<em class="mailheader">Content-Type</em> header of the message, or <em>failobj</em> if either
|
|||
|
|
the header is missing, or has no <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter. The returned
|
|||
|
|
string will always be unquoted as per <a class="reference internal" href="email.utils.html#email.utils.unquote" title="email.utils.unquote"><code class="xref py py-func docutils literal notranslate"><span class="pre">email.utils.unquote()</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.set_boundary">
|
|||
|
|
<code class="descname">set_boundary</code><span class="sig-paren">(</span><em>boundary</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_boundary" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Set the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter of the <em class="mailheader">Content-Type</em> header to
|
|||
|
|
<em>boundary</em>. <a class="reference internal" href="#email.message.EmailMessage.set_boundary" title="email.message.EmailMessage.set_boundary"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code></a> will always quote <em>boundary</em> if
|
|||
|
|
necessary. A <a class="reference internal" href="email.errors.html#email.errors.HeaderParseError" title="email.errors.HeaderParseError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">HeaderParseError</span></code></a> is raised if the
|
|||
|
|
message object has no <em class="mailheader">Content-Type</em> header.</p>
|
|||
|
|
<p>Note that using this method is subtly different from deleting the old
|
|||
|
|
<em class="mailheader">Content-Type</em> header and adding a new one with the new
|
|||
|
|
boundary via <a class="reference internal" href="#email.message.EmailMessage.add_header" title="email.message.EmailMessage.add_header"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_header()</span></code></a>, because <a class="reference internal" href="#email.message.EmailMessage.set_boundary" title="email.message.EmailMessage.set_boundary"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code></a> preserves
|
|||
|
|
the order of the <em class="mailheader">Content-Type</em> header in the list of
|
|||
|
|
headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content_charset">
|
|||
|
|
<code class="descname">get_content_charset</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_charset" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter of the <em class="mailheader">Content-Type</em> header,
|
|||
|
|
coerced to lower case. If there is no <em class="mailheader">Content-Type</em> header, or if
|
|||
|
|
that header has no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, <em>failobj</em> is returned.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_charsets">
|
|||
|
|
<code class="descname">get_charsets</code><span class="sig-paren">(</span><em>failobj=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_charsets" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return a list containing the character set names in the message. If the
|
|||
|
|
message is a <em class="mimetype">multipart</em>, then the list will contain one element
|
|||
|
|
for each subpart in the payload, otherwise, it will be a list of length 1.</p>
|
|||
|
|
<p>Each item in the list will be a string which is the value of the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter in the <em class="mailheader">Content-Type</em> header for the
|
|||
|
|
represented subpart. If the subpart has no <em class="mailheader">Content-Type</em>
|
|||
|
|
header, no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, or is not of the <em class="mimetype">text</em> main
|
|||
|
|
MIME type, then that item in the returned list will be <em>failobj</em>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.is_attachment">
|
|||
|
|
<code class="descname">is_attachment</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.is_attachment" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if there is a <em class="mailheader">Content-Disposition</em> header
|
|||
|
|
and its (case insensitive) value is <code class="docutils literal notranslate"><span class="pre">attachment</span></code>, <code class="docutils literal notranslate"><span class="pre">False</span></code> otherwise.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.4.2: </span>is_attachment is now a method instead of a property, for consistency
|
|||
|
|
with <a class="reference internal" href="email.compat32-message.html#email.message.Message.is_multipart" title="email.message.Message.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content_disposition">
|
|||
|
|
<code class="descname">get_content_disposition</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_disposition" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the lowercased value (without parameters) of the message’s
|
|||
|
|
<em class="mailheader">Content-Disposition</em> header if it has one, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. The
|
|||
|
|
possible values for this method are <em>inline</em>, <em>attachment</em> or <code class="docutils literal notranslate"><span class="pre">None</span></code>
|
|||
|
|
if the message follows <span class="target" id="index-10"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc2183.html"><strong>RFC 2183</strong></a>.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p>The following methods relate to interrogating and manipulating the content
|
|||
|
|
(payload) of the message.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.walk">
|
|||
|
|
<code class="descname">walk</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.walk" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <a class="reference internal" href="#email.message.EmailMessage.walk" title="email.message.EmailMessage.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a> method is an all-purpose generator which can be used to
|
|||
|
|
iterate over all the parts and subparts of a message object tree, in
|
|||
|
|
depth-first traversal order. You will typically use <a class="reference internal" href="#email.message.EmailMessage.walk" title="email.message.EmailMessage.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a> as the
|
|||
|
|
iterator in a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop; each iteration returns the next subpart.</p>
|
|||
|
|
<p>Here’s an example that prints the MIME type of every part of a multipart
|
|||
|
|
message structure:</p>
|
|||
|
|
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">msg</span><span class="o">.</span><span class="n">walk</span><span class="p">():</span>
|
|||
|
|
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">part</span><span class="o">.</span><span class="n">get_content_type</span><span class="p">())</span>
|
|||
|
|
<span class="go">multipart/report</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">message/delivery-status</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
<span class="go">message/rfc822</span>
|
|||
|
|
<span class="go">text/plain</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p><code class="docutils literal notranslate"><span class="pre">walk</span></code> iterates over the subparts of any part where
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.is_multipart" title="email.message.EmailMessage.is_multipart"><code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code></a> returns <code class="docutils literal notranslate"><span class="pre">True</span></code>, even though
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">msg.get_content_maintype()</span> <span class="pre">==</span> <span class="pre">'multipart'</span></code> may return <code class="docutils literal notranslate"><span class="pre">False</span></code>. We
|
|||
|
|
can see this in our example by making use of the <code class="docutils literal notranslate"><span class="pre">_structure</span></code> debug
|
|||
|
|
helper function:</p>
|
|||
|
|
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">for</span> <span class="n">part</span> <span class="ow">in</span> <span class="n">msg</span><span class="o">.</span><span class="n">walk</span><span class="p">():</span>
|
|||
|
|
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">part</span><span class="o">.</span><span class="n">get_content_maintype</span><span class="p">()</span> <span class="o">==</span> <span class="s1">'multipart'</span><span class="p">,</span>
|
|||
|
|
<span class="gp">... </span> <span class="n">part</span><span class="o">.</span><span class="n">is_multipart</span><span class="p">())</span>
|
|||
|
|
<span class="go">True True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="go">False True</span>
|
|||
|
|
<span class="go">False False</span>
|
|||
|
|
<span class="gp">>>> </span><span class="n">_structure</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
|
|||
|
|
<span class="go">multipart/report</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> message/delivery-status</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
<span class="go"> message/rfc822</span>
|
|||
|
|
<span class="go"> text/plain</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Here the <code class="docutils literal notranslate"><span class="pre">message</span></code> parts are not <code class="docutils literal notranslate"><span class="pre">multiparts</span></code>, but they do contain
|
|||
|
|
subparts. <code class="docutils literal notranslate"><span class="pre">is_multipart()</span></code> returns <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">walk</span></code> descends
|
|||
|
|
into the subparts.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_body">
|
|||
|
|
<code class="descname">get_body</code><span class="sig-paren">(</span><em>preferencelist=('related'</em>, <em>'html'</em>, <em>'plain')</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_body" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return the MIME part that is the best candidate to be the “body” of the
|
|||
|
|
message.</p>
|
|||
|
|
<p><em>preferencelist</em> must be a sequence of strings from the set <code class="docutils literal notranslate"><span class="pre">related</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">html</span></code>, and <code class="docutils literal notranslate"><span class="pre">plain</span></code>, and indicates the order of preference for the
|
|||
|
|
content type of the part returned.</p>
|
|||
|
|
<p>Start looking for candidate matches with the object on which the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">get_body</span></code> method is called.</p>
|
|||
|
|
<p>If <code class="docutils literal notranslate"><span class="pre">related</span></code> is not included in <em>preferencelist</em>, consider the root
|
|||
|
|
part (or subpart of the root part) of any related encountered as a
|
|||
|
|
candidate if the (sub-)part matches a preference.</p>
|
|||
|
|
<p>When encountering a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, check the <code class="docutils literal notranslate"><span class="pre">start</span></code> parameter
|
|||
|
|
and if a part with a matching <em class="mailheader">Content-ID</em> is found, consider
|
|||
|
|
only it when looking for candidate matches. Otherwise consider only the
|
|||
|
|
first (default root) part of the <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>.</p>
|
|||
|
|
<p>If a part has a <em class="mailheader">Content-Disposition</em> header, only consider
|
|||
|
|
the part a candidate match if the value of the header is <code class="docutils literal notranslate"><span class="pre">inline</span></code>.</p>
|
|||
|
|
<p>If none of the candidates matches any of the preferences in
|
|||
|
|
<em>preferencelist</em>, return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
<p>Notes: (1) For most applications the only <em>preferencelist</em> combinations
|
|||
|
|
that really make sense are <code class="docutils literal notranslate"><span class="pre">('plain',)</span></code>, <code class="docutils literal notranslate"><span class="pre">('html',</span> <span class="pre">'plain')</span></code>, and the
|
|||
|
|
default <code class="docutils literal notranslate"><span class="pre">('related',</span> <span class="pre">'html',</span> <span class="pre">'plain')</span></code>. (2) Because matching starts
|
|||
|
|
with the object on which <code class="docutils literal notranslate"><span class="pre">get_body</span></code> is called, calling <code class="docutils literal notranslate"><span class="pre">get_body</span></code> on
|
|||
|
|
a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code> will return the object itself unless
|
|||
|
|
<em>preferencelist</em> has a non-default value. (3) Messages (or message parts)
|
|||
|
|
that do not specify a <em class="mailheader">Content-Type</em> or whose
|
|||
|
|
<em class="mailheader">Content-Type</em> header is invalid will be treated as if they
|
|||
|
|
are of type <code class="docutils literal notranslate"><span class="pre">text/plain</span></code>, which may occasionally cause <code class="docutils literal notranslate"><span class="pre">get_body</span></code> to
|
|||
|
|
return unexpected results.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.iter_attachments">
|
|||
|
|
<code class="descname">iter_attachments</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.iter_attachments" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return an iterator over all of the immediate sub-parts of the message
|
|||
|
|
that are not candidate “body” parts. That is, skip the first occurrence
|
|||
|
|
of each of <code class="docutils literal notranslate"><span class="pre">text/plain</span></code>, <code class="docutils literal notranslate"><span class="pre">text/html</span></code>, <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, or
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code> (unless they are explicitly marked as
|
|||
|
|
attachments via <em class="mailheader">Content-Disposition: attachment</em>), and
|
|||
|
|
return all remaining parts. When applied directly to a
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, return an iterator over the all the related parts
|
|||
|
|
except the root part (ie: the part pointed to by the <code class="docutils literal notranslate"><span class="pre">start</span></code> parameter,
|
|||
|
|
or the first part if there is no <code class="docutils literal notranslate"><span class="pre">start</span></code> parameter or the <code class="docutils literal notranslate"><span class="pre">start</span></code>
|
|||
|
|
parameter doesn’t match the <em class="mailheader">Content-ID</em> of any of the
|
|||
|
|
parts). When applied directly to a <code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code> or a
|
|||
|
|
non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>, return an empty iterator.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.iter_parts">
|
|||
|
|
<code class="descname">iter_parts</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.iter_parts" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Return an iterator over all of the immediate sub-parts of the message,
|
|||
|
|
which will be empty for a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>. (See also
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.walk" title="email.message.EmailMessage.walk"><code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code></a>.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.get_content">
|
|||
|
|
<code class="descname">get_content</code><span class="sig-paren">(</span><em>*args</em>, <em>content_manager=None</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Call the <a class="reference internal" href="email.contentmanager.html#email.contentmanager.ContentManager.get_content" title="email.contentmanager.ContentManager.get_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content()</span></code></a> method
|
|||
|
|
of the <em>content_manager</em>, passing self as the message object, and passing
|
|||
|
|
along any other arguments or keywords as additional arguments. If
|
|||
|
|
<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified
|
|||
|
|
by the current <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.set_content">
|
|||
|
|
<code class="descname">set_content</code><span class="sig-paren">(</span><em>*args</em>, <em>content_manager=None</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_content" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Call the <a class="reference internal" href="email.contentmanager.html#email.contentmanager.ContentManager.set_content" title="email.contentmanager.ContentManager.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> method
|
|||
|
|
of the <em>content_manager</em>, passing self as the message object, and passing
|
|||
|
|
along any other arguments or keywords as additional arguments. If
|
|||
|
|
<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified
|
|||
|
|
by the current <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.make_related">
|
|||
|
|
<code class="descname">make_related</code><span class="sig-paren">(</span><em>boundary=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_related" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Convert a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code> message into a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code> message,
|
|||
|
|
moving any existing <em class="mailheader">Content-</em> headers and payload into a
|
|||
|
|
(new) first part of the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If <em>boundary</em> is specified, use
|
|||
|
|
it as the boundary string in the multipart, otherwise leave the boundary
|
|||
|
|
to be automatically created when it is needed (for example, when the
|
|||
|
|
message is serialized).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.make_alternative">
|
|||
|
|
<code class="descname">make_alternative</code><span class="sig-paren">(</span><em>boundary=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_alternative" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Convert a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code> or a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code> into a
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code>, moving any existing <em class="mailheader">Content-</em>
|
|||
|
|
headers and payload into a (new) first part of the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If
|
|||
|
|
<em>boundary</em> is specified, use it as the boundary string in the multipart,
|
|||
|
|
otherwise leave the boundary to be automatically created when it is
|
|||
|
|
needed (for example, when the message is serialized).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.make_mixed">
|
|||
|
|
<code class="descname">make_mixed</code><span class="sig-paren">(</span><em>boundary=None</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_mixed" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Convert a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>, a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, or a
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart-alternative</span></code> into a <code class="docutils literal notranslate"><span class="pre">multipart/mixed</span></code>, moving any existing
|
|||
|
|
<em class="mailheader">Content-</em> headers and payload into a (new) first part of the
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If <em>boundary</em> is specified, use it as the boundary string
|
|||
|
|
in the multipart, otherwise leave the boundary to be automatically
|
|||
|
|
created when it is needed (for example, when the message is serialized).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.add_related">
|
|||
|
|
<code class="descname">add_related</code><span class="sig-paren">(</span><em>*args</em>, <em>content_manager=None</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_related" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, create a new message
|
|||
|
|
object, pass all of the arguments to its <a class="reference internal" href="#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> method,
|
|||
|
|
and <a class="reference internal" href="email.compat32-message.html#email.message.Message.attach" title="email.message.Message.attach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">attach()</span></code></a> it to the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If
|
|||
|
|
the message is a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>, call <a class="reference internal" href="#email.message.EmailMessage.make_related" title="email.message.EmailMessage.make_related"><code class="xref py py-meth docutils literal notranslate"><span class="pre">make_related()</span></code></a> and then
|
|||
|
|
proceed as above. If the message is any other type of <code class="docutils literal notranslate"><span class="pre">multipart</span></code>,
|
|||
|
|
raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>. If <em>content_manager</em> is not specified, use
|
|||
|
|
the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified by the current <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>.
|
|||
|
|
If the added part has no <em class="mailheader">Content-Disposition</em> header,
|
|||
|
|
add one with the value <code class="docutils literal notranslate"><span class="pre">inline</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.add_alternative">
|
|||
|
|
<code class="descname">add_alternative</code><span class="sig-paren">(</span><em>*args</em>, <em>content_manager=None</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_alternative" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code>, create a new message
|
|||
|
|
object, pass all of the arguments to its <a class="reference internal" href="#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> method, and
|
|||
|
|
<a class="reference internal" href="email.compat32-message.html#email.message.Message.attach" title="email.message.Message.attach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">attach()</span></code></a> it to the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If the
|
|||
|
|
message is a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code> or <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, call
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage.make_alternative" title="email.message.EmailMessage.make_alternative"><code class="xref py py-meth docutils literal notranslate"><span class="pre">make_alternative()</span></code></a> and then proceed as above. If the message is
|
|||
|
|
any other type of <code class="docutils literal notranslate"><span class="pre">multipart</span></code>, raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>. If
|
|||
|
|
<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified
|
|||
|
|
by the current <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.add_attachment">
|
|||
|
|
<code class="descname">add_attachment</code><span class="sig-paren">(</span><em>*args</em>, <em>content_manager=None</em>, <em>**kw</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_attachment" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/mixed</span></code>, create a new message object,
|
|||
|
|
pass all of the arguments to its <a class="reference internal" href="#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> method, and
|
|||
|
|
<a class="reference internal" href="email.compat32-message.html#email.message.Message.attach" title="email.message.Message.attach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">attach()</span></code></a> it to the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>. If the
|
|||
|
|
message is a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>, <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, or
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code>, call <a class="reference internal" href="#email.message.EmailMessage.make_mixed" title="email.message.EmailMessage.make_mixed"><code class="xref py py-meth docutils literal notranslate"><span class="pre">make_mixed()</span></code></a> and then proceed as
|
|||
|
|
above. If <em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code>
|
|||
|
|
specified by the current <a class="reference internal" href="email.policy.html#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code class="xref py py-mod docutils literal notranslate"><span class="pre">policy</span></code></a>. If the added part
|
|||
|
|
has no <em class="mailheader">Content-Disposition</em> header, add one with the value
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">attachment</span></code>. This method can be used both for explicit attachments
|
|||
|
|
(<em class="mailheader">Content-Disposition: attachment</em>) and <code class="docutils literal notranslate"><span class="pre">inline</span></code> attachments
|
|||
|
|
(<em class="mailheader">Content-Disposition: inline</em>), by passing appropriate
|
|||
|
|
options to the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.clear">
|
|||
|
|
<code class="descname">clear</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.clear" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Remove the payload and all of the headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="email.message.EmailMessage.clear_content">
|
|||
|
|
<code class="descname">clear_content</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.clear_content" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Remove the payload and all of the <code class="xref py py-exc docutils literal notranslate"><span class="pre">Content-</span></code> headers, leaving
|
|||
|
|
all other headers intact and in their original order.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p><a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a> objects have the following instance attributes:</p>
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.EmailMessage.preamble">
|
|||
|
|
<code class="descname">preamble</code><a class="headerlink" href="#email.message.EmailMessage.preamble" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The format of a MIME document allows for some text between the blank line
|
|||
|
|
following the headers, and the first multipart boundary string. Normally,
|
|||
|
|
this text is never visible in a MIME-aware mail reader because it falls
|
|||
|
|
outside the standard MIME armor. However, when viewing the raw text of
|
|||
|
|
the message, or when viewing the message in a non-MIME aware reader, this
|
|||
|
|
text can become visible.</p>
|
|||
|
|
<p>The <em>preamble</em> attribute contains this leading extra-armor text for MIME
|
|||
|
|
documents. When the <a class="reference internal" href="email.parser.html#email.parser.Parser" title="email.parser.Parser"><code class="xref py py-class docutils literal notranslate"><span class="pre">Parser</span></code></a> discovers some text
|
|||
|
|
after the headers but before the first boundary string, it assigns this
|
|||
|
|
text to the message’s <em>preamble</em> attribute. When the
|
|||
|
|
<a class="reference internal" href="email.generator.html#email.generator.Generator" title="email.generator.Generator"><code class="xref py py-class docutils literal notranslate"><span class="pre">Generator</span></code></a> is writing out the plain text
|
|||
|
|
representation of a MIME message, and it finds the
|
|||
|
|
message has a <em>preamble</em> attribute, it will write this text in the area
|
|||
|
|
between the headers and the first boundary. See <a class="reference internal" href="email.parser.html#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code></a> and
|
|||
|
|
<a class="reference internal" href="email.generator.html#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.generator</span></code></a> for details.</p>
|
|||
|
|
<p>Note that if the message object has no preamble, the <em>preamble</em> attribute
|
|||
|
|
will be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.EmailMessage.epilogue">
|
|||
|
|
<code class="descname">epilogue</code><a class="headerlink" href="#email.message.EmailMessage.epilogue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <em>epilogue</em> attribute acts the same way as the <em>preamble</em> attribute,
|
|||
|
|
except that it contains text that appears between the last boundary and
|
|||
|
|
the end of the message. As with the <a class="reference internal" href="#email.message.EmailMessage.preamble" title="email.message.EmailMessage.preamble"><code class="xref py py-attr docutils literal notranslate"><span class="pre">preamble</span></code></a>,
|
|||
|
|
if there is no epilog text this attribute will be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="attribute">
|
|||
|
|
<dt id="email.message.EmailMessage.defects">
|
|||
|
|
<code class="descname">defects</code><a class="headerlink" href="#email.message.EmailMessage.defects" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The <em>defects</em> attribute contains a list of all the problems found when
|
|||
|
|
parsing this message. See <a class="reference internal" href="email.errors.html#module-email.errors" title="email.errors: The exception classes used by the email package."><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.errors</span></code></a> for a detailed description
|
|||
|
|
of the possible parsing defects.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="class">
|
|||
|
|
<dt id="email.message.MIMEPart">
|
|||
|
|
<em class="property">class </em><code class="descclassname">email.message.</code><code class="descname">MIMEPart</code><span class="sig-paren">(</span><em>policy=default</em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.MIMEPart" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>This class represents a subpart of a MIME message. It is identical to
|
|||
|
|
<a class="reference internal" href="#email.message.EmailMessage" title="email.message.EmailMessage"><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code></a>, except that no <em class="mailheader">MIME-Version</em> headers are
|
|||
|
|
added when <a class="reference internal" href="#email.message.EmailMessage.set_content" title="email.message.EmailMessage.set_content"><code class="xref py py-meth docutils literal notranslate"><span class="pre">set_content()</span></code></a> is called, since sub-parts do
|
|||
|
|
not need their own <em class="mailheader">MIME-Version</em> headers.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<p class="rubric">Footnotes</p>
|
|||
|
|
<dl class="footnote brackets">
|
|||
|
|
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
|
|||
|
|
<dd><p>Originally added in 3.4 as a <a class="reference internal" href="../glossary.html#term-provisional-package"><span class="xref std std-term">provisional module</span></a>. Docs for legacy message class moved to
|
|||
|
|
<a class="reference internal" href="email.compat32-message.html#compat32-message"><span class="std std-ref">email.message.Message: Representing an email message using the compat32 API</span></a>.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="email.html"
|
|||
|
|
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> — An email and MIME handling package</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="email.parser.html"
|
|||
|
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/email.message.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.parser.html" title="email.parser: Parsing email messages"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="email.html" title="email — An email and MIME handling package"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-3"><a href="email.html" ><code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> — An email and MIME handling package</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|