Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
email.message.html1103 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="email.message: Representing an email message" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/email.message.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/email/message.py The central class in the email package is the EmailMessage class, imported from the email.message module. It is the base class for the email object model. EmailMes..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_email.message_aaea02bc.png" />15<meta property="og:image:alt" content="Source code: Lib/email/message.py The central class in the email package is the EmailMessage class, imported from the email.message module. It is the base class for the email object model. EmailMes..." />16<meta name="description" content="Source code: Lib/email/message.py The central class in the email package is the EmailMessage class, imported from the email.message module. It is the base class for the email object model. EmailMes..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>email.message: Representing an email message &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="email.parser: Parsing email messages" href="email.parser.html" />43    <link rel="prev" title="email — An email and MIME handling package" href="email.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/email.message.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h4>Previous topic</h4>106    <p class="topless"><a href="email.html"107                          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>108  </div>109  <div>110    <h4>Next topic</h4>111    <p class="topless"><a href="email.parser.html"112                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a></p>113  </div>114  <script>115    document.addEventListener('DOMContentLoaded', () => {116        const title = document.querySelector('meta[property="og:title"]').content;117        const elements = document.querySelectorAll('.improvepage');118        const pageurl = window.location.href.split('?')[0];119        elements.forEach(element => {120            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));121            url.searchParams.set('pagetitle', title);122            url.searchParams.set('pageurl', pageurl);123            url.searchParams.set('pagesource', "library/email.message.rst");124            element.href = url.toString();125        });126    });127  </script>128  <div role="note" aria-label="source link">129    <h3>This page</h3>130    <ul class="this-page-menu">131      <li><a href="../bugs.html">Report a bug</a></li>132      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>133      <li>134        <a href="https://github.com/python/cpython/blob/main/Doc/library/email.message.rst?plain=1"135            rel="nofollow">Show source136        </a>137      </li>138      139    </ul>140  </div>141        </nav>142    </div>143</div>144 145  146    <div class="related" role="navigation" aria-label="Related">147      <h3>Navigation</h3>148      <ul>149        <li class="right" style="margin-right: 10px">150          <a href="../genindex.html" title="General Index"151             accesskey="I">index</a></li>152        <li class="right" >153          <a href="../py-modindex.html" title="Python Module Index"154             >modules</a> |</li>155        <li class="right" >156          <a href="email.parser.html" title="email.parser: Parsing email messages"157             accesskey="N">next</a> |</li>158        <li class="right" >159          <a href="email.html" title="email — An email and MIME handling package"160             accesskey="P">previous</a> |</li>161 162          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>163          <li><a href="https://www.python.org/">Python</a> &#187;</li>164          <li class="switchers">165            <div class="language_switcher_placeholder"></div>166            <div class="version_switcher_placeholder"></div>167          </li>168          <li>169              170          </li>171    <li id="cpython-language-and-version">172      <a href="../index.html">3.15.0a6 Documentation</a> &#187;173    </li>174 175          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>176          <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>177          <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> &#187;</li>178        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code>: Representing an email message</a></li>179                <li class="right">180                    181 182    <div class="inline-search" role="search">183        <form class="inline-search" action="../search.html" method="get">184          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">185          <input type="submit" value="Go">186        </form>187    </div>188                     |189                </li>190            <li class="right">191<label class="theme-selector-label">192    Theme193    <select class="theme-selector" oninput="activateTheme(this.value)">194        <option value="auto" selected>Auto</option>195        <option value="light">Light</option>196        <option value="dark">Dark</option>197    </select>198</label> |</li>199            200      </ul>201    </div>    202 203    <div class="document">204      <div class="documentwrapper">205        <div class="bodywrapper">206          <div class="body" role="main">207            208  <section id="module-email.message">209<span id="email-message-representing-an-email-message"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code>: Representing an email message<a class="headerlink" href="#module-email.message" title="Link to this heading">¶</a></h1>210<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/email/message.py">Lib/email/message.py</a></p>211<hr class="docutils" />212<div class="versionadded">213<p><span class="versionmodified added">Added in version 3.6: </span><a class="footnote-reference brackets" href="#id3" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>214</div>215<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>216class, imported from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code> module.  It is the base class for217the <code class="xref py py-mod docutils literal notranslate"><span class="pre">email</span></code> object model.  <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> provides the core218functionality for setting and querying header fields, for accessing message219bodies, and for creating or modifying structured messages.</p>220<p>An email message consists of <em>headers</em> and a <em>payload</em> (which is also referred221to as the <em>content</em>).  Headers are <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a> or <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6532.html"><strong>RFC 6532</strong></a> style field names222and values, where the field name and value are separated by a colon.  The colon223is not part of either the field name or the field value.  The payload may be a224simple text message, or a binary object, or a structured sequence of225sub-messages each with their own set of headers and their own payload.  The226latter type of payload is indicated by the message having a MIME type such as227<em class="mimetype">multipart/*</em> or <em class="mimetype">message/rfc822</em>.</p>228<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 an229ordered dictionary of headers coupled with a <em>payload</em> that represents the230<span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/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>231objects.  In addition to the normal dictionary methods for accessing the header232names and values, there are methods for accessing specialized information from233the headers (for example the MIME content type), for operating on the payload,234for generating a serialized version of the message, and for recursively walking235over the object tree.</p>236<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 header237names, which must be ASCII values.  The values of the dictionary are strings238with some extra methods.  Headers are stored and returned in case-preserving239form, but field names are matched case-insensitively.  The keys are ordered,240but unlike a real dict, there can be duplicates.  Additional methods are241provided for working with headers that have duplicate keys.</p>242<p>The <em>payload</em> is either a string or bytes object, in the case of simple message243objects, 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 container244documents such as <em class="mimetype">multipart/*</em> and <em class="mimetype">message/rfc822</em>245message objects.</p>246<dl class="py class">247<dt class="sig sig-object py" id="email.message.EmailMessage">248<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">email.message.</span></span><span class="sig-name descname"><span class="pre">EmailMessage</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">default</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage" title="Link to this definition">¶</a></dt>249<dd><p>If <em>policy</em> is specified use the rules it specifies to update and serialize250the representation of the message.  If <em>policy</em> is not set, use the251<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 email252RFCs except for line endings (instead of the RFC mandated <code class="docutils literal notranslate"><span class="pre">\r\n</span></code>, it uses253the Python standard <code class="docutils literal notranslate"><span class="pre">\n</span></code> line endings).  For more information see the254<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. <a class="footnote-reference brackets" href="#id4" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a></p>255<dl class="py method">256<dt class="sig sig-object py" id="email.message.EmailMessage.as_string">257<span class="sig-name descname"><span class="pre">as_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">unixfrom</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">maxheaderlen</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.as_string" title="Link to this definition">¶</a></dt>258<dd><p>Return the entire message flattened as a string.  When optional259<em>unixfrom</em> is true, the envelope header is included in the returned260string.  <em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.  For backward compatibility261with 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> is262accepted, but defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>, which means that by default the line263length is controlled by the264<a class="reference internal" href="email.policy.html#email.policy.Policy.max_line_length" title="email.policy.Policy.max_line_length"><code class="xref py py-attr docutils literal notranslate"><span class="pre">max_line_length</span></code></a> of the policy.  The265<em>policy</em> argument may be used to override the default policy obtained266from the message instance.  This can be used to control some of the267formatting produced by the method, since the specified <em>policy</em> will be268passed 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>269<p>Flattening the message may trigger changes to the <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code>270if defaults need to be filled in to complete the transformation to a271string (for example, MIME boundaries may be generated or modified).</p>272<p>Note that this method is provided as a convenience and may not be the273most useful way to serialize messages in your application, especially if274you are dealing with multiple messages.  See275<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 for276serializing messages.  Note also that this method is restricted to277producing messages serialized as “7 bit clean” when278<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>279<div class="versionchanged">280<p><span class="versionmodified changed">Changed in version 3.6: </span>the default behavior when <em>maxheaderlen</em>281is not specified was changed from defaulting to 0 to defaulting282to the value of <em>max_line_length</em> from the policy.</p>283</div>284</dd></dl>285 286<dl class="py method">287<dt class="sig sig-object py" id="email.message.EmailMessage.__str__">288<span class="sig-name descname"><span class="pre">__str__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__str__" title="Link to this definition">¶</a></dt>289<dd><p>Equivalent to <code class="docutils literal notranslate"><span class="pre">as_string(policy=self.policy.clone(utf8=True))</span></code>.  Allows290<code class="docutils literal notranslate"><span class="pre">str(msg)</span></code> to produce a string containing the serialized message in a291readable format.</p>292<div class="versionchanged">293<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>,294thus producing an <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6531.html"><strong>RFC 6531</strong></a>-like message representation, instead of295being 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>296</div>297</dd></dl>298 299<dl class="py method">300<dt class="sig sig-object py" id="email.message.EmailMessage.as_bytes">301<span class="sig-name descname"><span class="pre">as_bytes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">unixfrom</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.as_bytes" title="Link to this definition">¶</a></dt>302<dd><p>Return the entire message flattened as a bytes object.  When optional303<em>unixfrom</em> is true, the envelope header is included in the returned304string.  <em>unixfrom</em> defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.  The <em>policy</em> argument may be305used to override the default policy obtained from the message instance.306This can be used to control some of the formatting produced by the307method, since the specified <em>policy</em> will be passed to the308<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>309<p>Flattening the message may trigger changes to the <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code>310if defaults need to be filled in to complete the transformation to a311string (for example, MIME boundaries may be generated or modified).</p>312<p>Note that this method is provided as a convenience and may not be the313most useful way to serialize messages in your application, especially if314you are dealing with multiple messages.  See315<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 for316serializing messages.</p>317</dd></dl>318 319<dl class="py method">320<dt class="sig sig-object py" id="email.message.EmailMessage.__bytes__">321<span class="sig-name descname"><span class="pre">__bytes__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__bytes__" title="Link to this definition">¶</a></dt>322<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 a323bytes object containing the serialized message.</p>324</dd></dl>325 326<dl class="py method">327<dt class="sig sig-object py" id="email.message.EmailMessage.is_multipart">328<span class="sig-name descname"><span class="pre">is_multipart</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.is_multipart" title="Link to this definition">¶</a></dt>329<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the message’s payload is a list of330sub-<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> objects, otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.  When331<code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code> returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, the payload should be a string332object (which might be a CTE encoded binary payload).  Note that333<code class="xref py py-meth docutils literal notranslate"><span class="pre">is_multipart()</span></code> returning <code class="docutils literal notranslate"><span class="pre">True</span></code> does not necessarily mean that334“msg.get_content_maintype() == ‘multipart’” will return the <code class="docutils literal notranslate"><span class="pre">True</span></code>.335For 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 the336<code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> is of type <code class="docutils literal notranslate"><span class="pre">message/rfc822</span></code>.</p>337</dd></dl>338 339<dl class="py method">340<dt class="sig sig-object py" id="email.message.EmailMessage.set_unixfrom">341<span class="sig-name descname"><span class="pre">set_unixfrom</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">unixfrom</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_unixfrom" title="Link to this definition">¶</a></dt>342<dd><p>Set the message’s envelope header to <em>unixfrom</em>, which should be a343string.  (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 of344this header.)</p>345</dd></dl>346 347<dl class="py method">348<dt class="sig sig-object py" id="email.message.EmailMessage.get_unixfrom">349<span class="sig-name descname"><span class="pre">get_unixfrom</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_unixfrom" title="Link to this definition">¶</a></dt>350<dd><p>Return the message’s envelope header.  Defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code> if the351envelope header was never set.</p>352</dd></dl>353 354<p>The following methods implement the mapping-like interface for accessing the355message’s headers.  Note that there are some semantic differences356between these methods and a normal mapping (i.e. dictionary) interface.  For357example, in a dictionary there are no duplicate keys, but here there may be358duplicate message headers.  Also, in dictionaries there is no guaranteed359order 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 <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code>360object, headers are always returned in the order they appeared in the361original message, or in which they were added to the message later.  Any362header deleted and then re-added is always appended to the end of the363header list.</p>364<p>These semantic differences are intentional and are biased toward365convenience in the most common use cases.</p>366<p>Note that in all cases, any envelope header present in the message is not367included in the mapping interface.</p>368<dl class="py method">369<dt class="sig sig-object py" id="email.message.EmailMessage.__len__">370<span class="sig-name descname"><span class="pre">__len__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__len__" title="Link to this definition">¶</a></dt>371<dd><p>Return the total number of headers, including duplicates.</p>372</dd></dl>373 374<dl class="py method">375<dt class="sig sig-object py" id="email.message.EmailMessage.__contains__">376<span class="sig-name descname"><span class="pre">__contains__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__contains__" title="Link to this definition">¶</a></dt>377<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the message object has a field named <em>name</em>. Matching is378done without regard to case and <em>name</em> does not include the trailing379colon.  Used for the <code class="docutils literal notranslate"><span class="pre">in</span></code> operator.  For example:</p>380<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="s1">&#39;message-id&#39;</span> <span class="ow">in</span> <span class="n">myMessage</span><span class="p">:</span>381   <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;Message-ID:&#39;</span><span class="p">,</span> <span class="n">myMessage</span><span class="p">[</span><span class="s1">&#39;message-id&#39;</span><span class="p">])</span>382</pre></div>383</div>384</dd></dl>385 386<dl class="py method">387<dt class="sig sig-object py" id="email.message.EmailMessage.__getitem__">388<span class="sig-name descname"><span class="pre">__getitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__getitem__" title="Link to this definition">¶</a></dt>389<dd><p>Return the value of the named header field.  <em>name</em> does not include the390colon field separator.  If the header is missing, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned; a391<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>392<p>Note that if the named field appears more than once in the message’s393headers, exactly which of those field values will be returned is394undefined.  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 the395extant headers named <em>name</em>.</p>396<p>Using the standard (non-<code class="docutils literal notranslate"><span class="pre">compat32</span></code>) policies, the returned value is an397instance 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>398</dd></dl>399 400<dl class="py method">401<dt class="sig sig-object py" id="email.message.EmailMessage.__setitem__">402<span class="sig-name descname"><span class="pre">__setitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">val</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__setitem__" title="Link to this definition">¶</a></dt>403<dd><p>Add a header to the message with field name <em>name</em> and value <em>val</em>.  The404field is appended to the end of the message’s existing headers.</p>405<p>Note that this does <em>not</em> overwrite or delete any existing header with the same406name.  If you want to ensure that the new header is the only one present in the407message with field name <em>name</em>, delete the field first, e.g.:</p>408<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">&#39;subject&#39;</span><span class="p">]</span>409<span class="n">msg</span><span class="p">[</span><span class="s1">&#39;subject&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;Python roolz!&#39;</span>410</pre></div>411</div>412<p>If 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> defines certain headers to be unique (as the standard413policies 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 attempt414is made to assign a value to such a header when one already exists.  This415behavior is intentional for consistency’s sake, but do not depend on it416as we may choose to make such assignments do an automatic deletion of the417existing header in the future.</p>418</dd></dl>419 420<dl class="py method">421<dt class="sig sig-object py" id="email.message.EmailMessage.__delitem__">422<span class="sig-name descname"><span class="pre">__delitem__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.__delitem__" title="Link to this definition">¶</a></dt>423<dd><p>Delete all occurrences of the field with name <em>name</em> from the message’s424headers.  No exception is raised if the named field isn’t present in the425headers.</p>426</dd></dl>427 428<dl class="py method">429<dt class="sig sig-object py" id="email.message.EmailMessage.keys">430<span class="sig-name descname"><span class="pre">keys</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.keys" title="Link to this definition">¶</a></dt>431<dd><p>Return a list of all the message’s header field names.</p>432</dd></dl>433 434<dl class="py method">435<dt class="sig sig-object py" id="email.message.EmailMessage.values">436<span class="sig-name descname"><span class="pre">values</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.values" title="Link to this definition">¶</a></dt>437<dd><p>Return a list of all the message’s field values.</p>438</dd></dl>439 440<dl class="py method">441<dt class="sig sig-object py" id="email.message.EmailMessage.items">442<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.items" title="Link to this definition">¶</a></dt>443<dd><p>Return a list of 2-tuples containing all the message’s field headers and444values.</p>445</dd></dl>446 447<dl class="py method">448<dt class="sig sig-object py" id="email.message.EmailMessage.get">449<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get" title="Link to this definition">¶</a></dt>450<dd><p>Return the value of the named header field.  This is identical to451<a class="reference internal" href="../reference/datamodel.html#object.__getitem__" title="object.__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 the452named header is missing (<em>failobj</em> defaults to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>453</dd></dl>454 455<p>Here are some additional useful header related methods:</p>456<dl class="py method">457<dt class="sig sig-object py" id="email.message.EmailMessage.get_all">458<span class="sig-name descname"><span class="pre">get_all</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_all" title="Link to this definition">¶</a></dt>459<dd><p>Return a list of all the values for the field named <em>name</em>. If there are460no such named headers in the message, <em>failobj</em> is returned (defaults to461<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>462</dd></dl>463 464<dl class="py method">465<dt class="sig sig-object py" id="email.message.EmailMessage.add_header">466<span class="sig-name descname"><span class="pre">add_header</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_value</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">_params</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_header" title="Link to this definition">¶</a></dt>467<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>468except that additional header parameters can be provided as keyword469arguments.  <em>_name</em> is the header field to add and <em>_value</em> is the470<em>primary</em> value for the header.</p>471<p>For each item in the keyword argument dictionary <em>_params</em>, the key is472taken as the parameter name, with underscores converted to dashes (since473dashes are illegal in Python identifiers).  Normally, the parameter will474be added as <code class="docutils literal notranslate"><span class="pre">key=&quot;value&quot;</span></code> unless the value is <code class="docutils literal notranslate"><span class="pre">None</span></code>, in which case475only the key will be added.</p>476<p>If the value contains non-ASCII characters, the charset and language may477be explicitly controlled by specifying the value as a three tuple in the478format <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 string479naming the charset to be used to encode the value, <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> can480usually 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://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a> for other481possibilities), and <code class="docutils literal notranslate"><span class="pre">VALUE</span></code> is the string value containing non-ASCII482code points.  If a three tuple is not passed and the value contains483non-ASCII characters, it is automatically encoded in <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a> format484using 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>485<p>Here is an example:</p>486<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">&#39;Content-Disposition&#39;</span><span class="p">,</span> <span class="s1">&#39;attachment&#39;</span><span class="p">,</span> <span class="n">filename</span><span class="o">=</span><span class="s1">&#39;bud.gif&#39;</span><span class="p">)</span>487</pre></div>488</div>489<p>This will add a header that looks like</p>490<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">&quot;bud.gif&quot;</span>491</pre></div>492</div>493<p>An example of the extended interface with non-ASCII characters:</p>494<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">&#39;Content-Disposition&#39;</span><span class="p">,</span> <span class="s1">&#39;attachment&#39;</span><span class="p">,</span>495               <span class="n">filename</span><span class="o">=</span><span class="p">(</span><span class="s1">&#39;iso-8859-1&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="s1">&#39;Fußballer.ppt&#39;</span><span class="p">))</span>496</pre></div>497</div>498</dd></dl>499 500<dl class="py method">501<dt class="sig sig-object py" id="email.message.EmailMessage.replace_header">502<span class="sig-name descname"><span class="pre">replace_header</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">_name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">_value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.replace_header" title="Link to this definition">¶</a></dt>503<dd><p>Replace a header.  Replace the first header found in the message that504matches <em>_name</em>, retaining header order and field name case of the505original header.  If no matching header is found, raise a506<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>507</dd></dl>508 509<dl class="py method">510<dt class="sig sig-object py" id="email.message.EmailMessage.get_content_type">511<span class="sig-name descname"><span class="pre">get_content_type</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_type" title="Link to this definition">¶</a></dt>512<dd><p>Return the message’s content type, coerced to lower case of the form513<em class="mimetype">maintype/subtype</em>.  If there is no <em class="mailheader">Content-Type</em>514header in the message return the value returned by515<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 is516invalid, return <code class="docutils literal notranslate"><span class="pre">text/plain</span></code>.</p>517<p>(According to <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2045.html"><strong>RFC 2045</strong></a>, messages always have a default type,518<code class="xref py py-meth docutils literal notranslate"><span class="pre">get_content_type()</span></code> will always return a value.  <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2045.html"><strong>RFC 2045</strong></a> defines519a message’s default type to be <em class="mimetype">text/plain</em> unless it appears520inside a <em class="mimetype">multipart/digest</em> container, in which case it would521be <em class="mimetype">message/rfc822</em>.  If the <em class="mailheader">Content-Type</em> header522has an invalid type specification, <span class="target" id="index-8"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2045.html"><strong>RFC 2045</strong></a> mandates that the default523type be <em class="mimetype">text/plain</em>.)</p>524</dd></dl>525 526<dl class="py method">527<dt class="sig sig-object py" id="email.message.EmailMessage.get_content_maintype">528<span class="sig-name descname"><span class="pre">get_content_maintype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_maintype" title="Link to this definition">¶</a></dt>529<dd><p>Return the message’s main content type.  This is the <em class="mimetype">maintype</em>530part 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>531</dd></dl>532 533<dl class="py method">534<dt class="sig sig-object py" id="email.message.EmailMessage.get_content_subtype">535<span class="sig-name descname"><span class="pre">get_content_subtype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_subtype" title="Link to this definition">¶</a></dt>536<dd><p>Return the message’s sub-content type.  This is the <em class="mimetype">subtype</em>537part 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>538</dd></dl>539 540<dl class="py method">541<dt class="sig sig-object py" id="email.message.EmailMessage.get_default_type">542<span class="sig-name descname"><span class="pre">get_default_type</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_default_type" title="Link to this definition">¶</a></dt>543<dd><p>Return the default content type.  Most messages have a default content544type of <em class="mimetype">text/plain</em>, except for messages that are subparts of545<em class="mimetype">multipart/digest</em> containers.  Such subparts have a default546content type of <em class="mimetype">message/rfc822</em>.</p>547</dd></dl>548 549<dl class="py method">550<dt class="sig sig-object py" id="email.message.EmailMessage.set_default_type">551<span class="sig-name descname"><span class="pre">set_default_type</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ctype</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_default_type" title="Link to this definition">¶</a></dt>552<dd><p>Set the default content type.  <em>ctype</em> should either be553<em class="mimetype">text/plain</em> or <em class="mimetype">message/rfc822</em>, although this is554not enforced.  The default content type is not stored in the555<em class="mailheader">Content-Type</em> header, so it only affects the return value of556the <code class="docutils literal notranslate"><span class="pre">get_content_type</span></code> methods when no <em class="mailheader">Content-Type</em>557header is present in the message.</p>558</dd></dl>559 560<dl class="py method">561<dt class="sig sig-object py" id="email.message.EmailMessage.set_param">562<span class="sig-name descname"><span class="pre">set_param</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">param</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">header</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'Content-Type'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">requote</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">charset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">language</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">replace</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_param" title="Link to this definition">¶</a></dt>563<dd><p>Set a parameter in the <em class="mailheader">Content-Type</em> header.  If the564parameter already exists in the header, replace its value with <em>value</em>.565When <em>header</em> is <code class="docutils literal notranslate"><span class="pre">Content-Type</span></code> (the default) and the header does not566yet exist in the message, add it, set its value to567<em class="mimetype">text/plain</em>, and append the new parameter value.  Optional568<em>header</em> specifies an alternative header to <em class="mailheader">Content-Type</em>.</p>569<p>If the value contains non-ASCII characters, the charset and language may570be explicitly specified using the optional <em>charset</em> and <em>language</em>571parameters.  Optional <em>language</em> specifies the <span class="target" id="index-9"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a> language,572defaulting to the empty string.  Both <em>charset</em> and <em>language</em> should be573strings.  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> for574the <em>language</em>.</p>575<p>If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the default) the header is moved to the576end of the list of headers.  If <em>replace</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the header577will be updated in place.</p>578<p>Use of the <em>requote</em> parameter with <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> objects is579deprecated.</p>580<p>Note that existing parameter values of headers may be accessed through581the <a class="reference internal" href="email.headerregistry.html#email.headerregistry.ParameterizedMIMEHeader.params" title="email.headerregistry.ParameterizedMIMEHeader.params"><code class="xref py py-attr docutils literal notranslate"><span class="pre">params</span></code></a> attribute of the582header value (for example, <code class="docutils literal notranslate"><span class="pre">msg['Content-Type'].params['charset']</span></code>).</p>583<div class="versionchanged">584<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>585</div>586</dd></dl>587 588<dl class="py method">589<dt class="sig sig-object py" id="email.message.EmailMessage.del_param">590<span class="sig-name descname"><span class="pre">del_param</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">param</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">header</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'content-type'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">requote</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.del_param" title="Link to this definition">¶</a></dt>591<dd><p>Remove the given parameter completely from the <em class="mailheader">Content-Type</em>592header.  The header will be re-written in place without the parameter or593its value.  Optional <em>header</em> specifies an alternative to594<em class="mailheader">Content-Type</em>.</p>595<p>Use of the <em>requote</em> parameter with <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> objects is596deprecated.</p>597</dd></dl>598 599<dl class="py method">600<dt class="sig sig-object py" id="email.message.EmailMessage.get_filename">601<span class="sig-name descname"><span class="pre">get_filename</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_filename" title="Link to this definition">¶</a></dt>602<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter of the603<em class="mailheader">Content-Disposition</em> header of the message.  If the header604does not have a <code class="docutils literal notranslate"><span class="pre">filename</span></code> parameter, this method falls back to looking605for the <code class="docutils literal notranslate"><span class="pre">name</span></code> parameter on the <em class="mailheader">Content-Type</em> header.  If606neither is found, or the header is missing, then <em>failobj</em> is returned.607The returned string will always be unquoted as per608<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>609</dd></dl>610 611<dl class="py method">612<dt class="sig sig-object py" id="email.message.EmailMessage.get_boundary">613<span class="sig-name descname"><span class="pre">get_boundary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_boundary" title="Link to this definition">¶</a></dt>614<dd><p>Return the value of the <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter of the615<em class="mailheader">Content-Type</em> header of the message, or <em>failobj</em> if either616the header is missing, or has no <code class="docutils literal notranslate"><span class="pre">boundary</span></code> parameter.  The returned617string 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>618</dd></dl>619 620<dl class="py method">621<dt class="sig sig-object py" id="email.message.EmailMessage.set_boundary">622<span class="sig-name descname"><span class="pre">set_boundary</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">boundary</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_boundary" title="Link to this definition">¶</a></dt>623<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 to624<em>boundary</em>.  <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code> will always quote <em>boundary</em> if625necessary.  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 the626message object has no <em class="mailheader">Content-Type</em> header.</p>627<p>Note that using this method is subtly different from deleting the old628<em class="mailheader">Content-Type</em> header and adding a new one with the new629boundary 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 <code class="xref py py-meth docutils literal notranslate"><span class="pre">set_boundary()</span></code> preserves630the order of the <em class="mailheader">Content-Type</em> header in the list of631headers.</p>632</dd></dl>633 634<dl class="py method">635<dt class="sig sig-object py" id="email.message.EmailMessage.get_content_charset">636<span class="sig-name descname"><span class="pre">get_content_charset</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_charset" title="Link to this definition">¶</a></dt>637<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,638coerced to lower case.  If there is no <em class="mailheader">Content-Type</em> header, or if639that header has no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, <em>failobj</em> is returned.</p>640</dd></dl>641 642<dl class="py method">643<dt class="sig sig-object py" id="email.message.EmailMessage.get_charsets">644<span class="sig-name descname"><span class="pre">get_charsets</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">failobj</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_charsets" title="Link to this definition">¶</a></dt>645<dd><p>Return a list containing the character set names in the message.  If the646message is a <em class="mimetype">multipart</em>, then the list will contain one element647for each subpart in the payload, otherwise, it will be a list of length 1.</p>648<p>Each item in the list will be a string which is the value of the649<code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter in the <em class="mailheader">Content-Type</em> header for the650represented subpart.  If the subpart has no <em class="mailheader">Content-Type</em>651header, no <code class="docutils literal notranslate"><span class="pre">charset</span></code> parameter, or is not of the <em class="mimetype">text</em> main652MIME type, then that item in the returned list will be <em>failobj</em>.</p>653</dd></dl>654 655<dl class="py method">656<dt class="sig sig-object py" id="email.message.EmailMessage.is_attachment">657<span class="sig-name descname"><span class="pre">is_attachment</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.is_attachment" title="Link to this definition">¶</a></dt>658<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if there is a <em class="mailheader">Content-Disposition</em> header659and 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>660<div class="versionchanged">661<p><span class="versionmodified changed">Changed in version 3.4.2: </span>is_attachment is now a method instead of a property, for consistency662with <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>663</div>664</dd></dl>665 666<dl class="py method">667<dt class="sig sig-object py" id="email.message.EmailMessage.get_content_disposition">668<span class="sig-name descname"><span class="pre">get_content_disposition</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content_disposition" title="Link to this definition">¶</a></dt>669<dd><p>Return the lowercased value (without parameters) of the message’s670<em class="mailheader">Content-Disposition</em> header if it has one, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.  The671possible values for this method are <em>inline</em>, <em>attachment</em> or <code class="docutils literal notranslate"><span class="pre">None</span></code>672if the message follows <span class="target" id="index-10"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2183.html"><strong>RFC 2183</strong></a>.</p>673<div class="versionadded">674<p><span class="versionmodified added">Added in version 3.5.</span></p>675</div>676</dd></dl>677 678<p>The following methods relate to interrogating and manipulating the content679(payload) of the message.</p>680<dl class="py method">681<dt class="sig sig-object py" id="email.message.EmailMessage.walk">682<span class="sig-name descname"><span class="pre">walk</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.walk" title="Link to this definition">¶</a></dt>683<dd><p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code> method is an all-purpose generator which can be used to684iterate over all the parts and subparts of a message object tree, in685depth-first traversal order.  You will typically use <code class="xref py py-meth docutils literal notranslate"><span class="pre">walk()</span></code> as the686iterator in a <code class="docutils literal notranslate"><span class="pre">for</span></code> loop; each iteration returns the next subpart.</p>687<p>Here’s an example that prints the MIME type of every part of a multipart688message structure:</p>689<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>690<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>691<span class="go">multipart/report</span>692<span class="go">text/plain</span>693<span class="go">message/delivery-status</span>694<span class="go">text/plain</span>695<span class="go">text/plain</span>696<span class="go">message/rfc822</span>697<span class="go">text/plain</span>698</pre></div>699</div>700<p><code class="docutils literal notranslate"><span class="pre">walk</span></code> iterates over the subparts of any part where701<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 though702<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>.  We703can see this in our example by making use of the <code class="docutils literal notranslate"><span class="pre">_structure</span></code> debug704helper function:</p>705<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">email.iterators</span><span class="w"> </span><span class="kn">import</span> <span class="n">_structure</span>706<span class="gp">&gt;&gt;&gt; </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>707<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">&#39;multipart&#39;</span><span class="p">,</span>708<span class="gp">... </span>          <span class="n">part</span><span class="o">.</span><span class="n">is_multipart</span><span class="p">())</span>709<span class="go">True True</span>710<span class="go">False False</span>711<span class="go">False True</span>712<span class="go">False False</span>713<span class="go">False False</span>714<span class="go">False True</span>715<span class="go">False False</span>716<span class="gp">&gt;&gt;&gt; </span><span class="n">_structure</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>717<span class="go">multipart/report</span>718<span class="go">    text/plain</span>719<span class="go">    message/delivery-status</span>720<span class="go">        text/plain</span>721<span class="go">        text/plain</span>722<span class="go">    message/rfc822</span>723<span class="go">        text/plain</span>724</pre></div>725</div>726<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 contain727subparts. <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> descends728into the subparts.</p>729</dd></dl>730 731<dl class="py method">732<dt class="sig sig-object py" id="email.message.EmailMessage.get_body">733<span class="sig-name descname"><span class="pre">get_body</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">preferencelist</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">('related',</span> <span class="pre">'html',</span> <span class="pre">'plain')</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_body" title="Link to this definition">¶</a></dt>734<dd><p>Return the MIME part that is the best candidate to be the “body” of the735message.</p>736<p><em>preferencelist</em> must be a sequence of strings from the set <code class="docutils literal notranslate"><span class="pre">related</span></code>,737<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 the738content type of the part returned.</p>739<p>Start looking for candidate matches with the object on which the740<code class="docutils literal notranslate"><span class="pre">get_body</span></code> method is called.</p>741<p>If <code class="docutils literal notranslate"><span class="pre">related</span></code> is not included in <em>preferencelist</em>, consider the root742part (or subpart of the root part) of any related encountered as a743candidate if the (sub-)part matches a preference.</p>744<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> parameter745and if a part with a matching <em class="mailheader">Content-ID</em> is found, consider746only it when looking for candidate matches.  Otherwise consider only the747first (default root) part of the <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>.</p>748<p>If a part has a <em class="mailheader">Content-Disposition</em> header, only consider749the part a candidate match if the value of the header is <code class="docutils literal notranslate"><span class="pre">inline</span></code>.</p>750<p>If none of the candidates matches any of the preferences in751<em>preferencelist</em>, return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>752<p>Notes: (1) For most applications the only <em>preferencelist</em> combinations753that 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 the754default <code class="docutils literal notranslate"><span class="pre">('related',</span> <span class="pre">'html',</span> <span class="pre">'plain')</span></code>.  (2) Because matching starts755with 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> on756a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code> will return the object itself unless757<em>preferencelist</em> has a non-default value. (3) Messages (or message parts)758that do not specify a <em class="mailheader">Content-Type</em> or whose759<em class="mailheader">Content-Type</em> header is invalid will be treated as if they760are 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> to761return unexpected results.</p>762</dd></dl>763 764<dl class="py method">765<dt class="sig sig-object py" id="email.message.EmailMessage.iter_attachments">766<span class="sig-name descname"><span class="pre">iter_attachments</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.iter_attachments" title="Link to this definition">¶</a></dt>767<dd><p>Return an iterator over all of the immediate sub-parts of the message768that are not candidate “body” parts.  That is, skip the first occurrence769of 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>, or770<code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code> (unless they are explicitly marked as771attachments via <em class="mailheader">Content-Disposition: attachment</em>), and772return all remaining parts.  When applied directly to a773<code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, return an iterator over the all the related parts774except the root part (ie: the part pointed to by the <code class="docutils literal notranslate"><span class="pre">start</span></code> parameter,775or 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>776parameter doesn’t match the <em class="mailheader">Content-ID</em> of any of the777parts).  When applied directly to a <code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code> or a778non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>, return an empty iterator.</p>779</dd></dl>780 781<dl class="py method">782<dt class="sig sig-object py" id="email.message.EmailMessage.iter_parts">783<span class="sig-name descname"><span class="pre">iter_parts</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.iter_parts" title="Link to this definition">¶</a></dt>784<dd><p>Return an iterator over all of the immediate sub-parts of the message,785which will be empty for a non-<code class="docutils literal notranslate"><span class="pre">multipart</span></code>.  (See also786<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>787</dd></dl>788 789<dl class="py method">790<dt class="sig sig-object py" id="email.message.EmailMessage.get_content">791<span class="sig-name descname"><span class="pre">get_content</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">content_manager</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.get_content" title="Link to this definition">¶</a></dt>792<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> method793of the <em>content_manager</em>, passing self as the message object, and passing794along any other arguments or keywords as additional arguments.  If795<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified796by 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>797</dd></dl>798 799<dl class="py method">800<dt class="sig sig-object py" id="email.message.EmailMessage.set_content">801<span class="sig-name descname"><span class="pre">set_content</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">content_manager</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.set_content" title="Link to this definition">¶</a></dt>802<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> method803of the <em>content_manager</em>, passing self as the message object, and passing804along any other arguments or keywords as additional arguments.  If805<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified806by 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>807</dd></dl>808 809<dl class="py method">810<dt class="sig sig-object py" id="email.message.EmailMessage.make_related">811<span class="sig-name descname"><span class="pre">make_related</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">boundary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_related" title="Link to this definition">¶</a></dt>812<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,813moving any existing <em class="mailheader">Content-</em> headers and payload into a814(new) first part of the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>.  If <em>boundary</em> is specified, use815it as the boundary string in the multipart, otherwise leave the boundary816to be automatically created when it is needed (for example, when the817message is serialized).</p>818</dd></dl>819 820<dl class="py method">821<dt class="sig sig-object py" id="email.message.EmailMessage.make_alternative">822<span class="sig-name descname"><span class="pre">make_alternative</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">boundary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_alternative" title="Link to this definition">¶</a></dt>823<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 a824<code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code>, moving any existing <em class="mailheader">Content-</em>825headers and payload into a (new) first part of the <code class="docutils literal notranslate"><span class="pre">multipart</span></code>.  If826<em>boundary</em> is specified, use it as the boundary string in the multipart,827otherwise leave the boundary to be automatically created when it is828needed (for example, when the message is serialized).</p>829</dd></dl>830 831<dl class="py method">832<dt class="sig sig-object py" id="email.message.EmailMessage.make_mixed">833<span class="sig-name descname"><span class="pre">make_mixed</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">boundary</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.make_mixed" title="Link to this definition">¶</a></dt>834<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 a835<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 existing836<em class="mailheader">Content-</em> headers and payload into a (new) first part of the837<code class="docutils literal notranslate"><span class="pre">multipart</span></code>.  If <em>boundary</em> is specified, use it as the boundary string838in the multipart, otherwise leave the boundary to be automatically839created when it is needed (for example, when the message is serialized).</p>840</dd></dl>841 842<dl class="py method">843<dt class="sig sig-object py" id="email.message.EmailMessage.add_related">844<span class="sig-name descname"><span class="pre">add_related</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">content_manager</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_related" title="Link to this definition">¶</a></dt>845<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/related</span></code>, create a new message846object, 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,847and <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>.  If848the 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 then849proceed as above.  If the message is any other type of <code class="docutils literal notranslate"><span class="pre">multipart</span></code>,850raise 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, use851the <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>.852If the added part has no <em class="mailheader">Content-Disposition</em> header,853add one with the value <code class="docutils literal notranslate"><span class="pre">inline</span></code>.</p>854</dd></dl>855 856<dl class="py method">857<dt class="sig sig-object py" id="email.message.EmailMessage.add_alternative">858<span class="sig-name descname"><span class="pre">add_alternative</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">content_manager</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_alternative" title="Link to this definition">¶</a></dt>859<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/alternative</span></code>, create a new message860object, 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, and861<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 the862message 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>, call863<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 is864any 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>. If865<em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code> specified866by 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>867</dd></dl>868 869<dl class="py method">870<dt class="sig sig-object py" id="email.message.EmailMessage.add_attachment">871<span class="sig-name descname"><span class="pre">add_attachment</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">content_manager</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.add_attachment" title="Link to this definition">¶</a></dt>872<dd><p>If the message is a <code class="docutils literal notranslate"><span class="pre">multipart/mixed</span></code>, create a new message object,873pass 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, and874<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 the875message 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>, or876<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 as877above. If <em>content_manager</em> is not specified, use the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code>878specified 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 part879has no <em class="mailheader">Content-Disposition</em> header, add one with the value880<code class="docutils literal notranslate"><span class="pre">attachment</span></code>.  This method can be used both for explicit attachments881(<em class="mailheader">Content-Disposition: attachment</em>) and <code class="docutils literal notranslate"><span class="pre">inline</span></code> attachments882(<em class="mailheader">Content-Disposition: inline</em>), by passing appropriate883options to the <code class="docutils literal notranslate"><span class="pre">content_manager</span></code>.</p>884</dd></dl>885 886<dl class="py method">887<dt class="sig sig-object py" id="email.message.EmailMessage.clear">888<span class="sig-name descname"><span class="pre">clear</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.clear" title="Link to this definition">¶</a></dt>889<dd><p>Remove the payload and all of the headers.</p>890</dd></dl>891 892<dl class="py method">893<dt class="sig sig-object py" id="email.message.EmailMessage.clear_content">894<span class="sig-name descname"><span class="pre">clear_content</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#email.message.EmailMessage.clear_content" title="Link to this definition">¶</a></dt>895<dd><p>Remove the payload and all of the <em class="mailheader">!Content-</em> headers, leaving896all other headers intact and in their original order.</p>897</dd></dl>898 899<p><code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code> objects have the following instance attributes:</p>900<dl class="py attribute">901<dt class="sig sig-object py" id="email.message.EmailMessage.preamble">902<span class="sig-name descname"><span class="pre">preamble</span></span><a class="headerlink" href="#email.message.EmailMessage.preamble" title="Link to this definition">¶</a></dt>903<dd><p>The format of a MIME document allows for some text between the blank line904following the headers, and the first multipart boundary string. Normally,905this text is never visible in a MIME-aware mail reader because it falls906outside the standard MIME armor.  However, when viewing the raw text of907the message, or when viewing the message in a non-MIME aware reader, this908text can become visible.</p>909<p>The <em>preamble</em> attribute contains this leading extra-armor text for MIME910documents.  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 text911after the headers but before the first boundary string, it assigns this912text to the message’s <em>preamble</em> attribute.  When the913<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 text914representation of a MIME message, and it finds the915message has a <em>preamble</em> attribute, it will write this text in the area916between 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> and917<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>918<p>Note that if the message object has no preamble, the <em>preamble</em> attribute919will be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>920</dd></dl>921 922<dl class="py attribute">923<dt class="sig sig-object py" id="email.message.EmailMessage.epilogue">924<span class="sig-name descname"><span class="pre">epilogue</span></span><a class="headerlink" href="#email.message.EmailMessage.epilogue" title="Link to this definition">¶</a></dt>925<dd><p>The <em>epilogue</em> attribute acts the same way as the <em>preamble</em> attribute,926except that it contains text that appears between the last boundary and927the 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>,928if there is no epilog text this attribute will be <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>929</dd></dl>930 931<dl class="py attribute">932<dt class="sig sig-object py" id="email.message.EmailMessage.defects">933<span class="sig-name descname"><span class="pre">defects</span></span><a class="headerlink" href="#email.message.EmailMessage.defects" title="Link to this definition">¶</a></dt>934<dd><p>The <em>defects</em> attribute contains a list of all the problems found when935parsing 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 description936of the possible parsing defects.</p>937</dd></dl>938 939</dd></dl>940 941<dl class="py class">942<dt class="sig sig-object py" id="email.message.MIMEPart">943<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">email.message.</span></span><span class="sig-name descname"><span class="pre">MIMEPart</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">policy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">default</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#email.message.MIMEPart" title="Link to this definition">¶</a></dt>944<dd><p>This class represents a subpart of a MIME message.  It is identical to945<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 are946added 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 do947not need their own <em class="mailheader">MIME-Version</em> headers.</p>948</dd></dl>949 950<p class="rubric">Footnotes</p>951<aside class="footnote-list brackets">952<aside class="footnote brackets" id="id3" role="doc-footnote">953<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>954<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 to955<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>956</aside>957<aside class="footnote brackets" id="id4" role="doc-footnote">958<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id2">2</a><span class="fn-bracket">]</span></span>959<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> class requires a policy that provides a960<code class="docutils literal notranslate"><span class="pre">content_manager</span></code> attribute for content management methods like961<code class="docutils literal notranslate"><span class="pre">set_content()</span></code> and <code class="docutils literal notranslate"><span class="pre">get_content()</span></code> to work. The legacy962<a class="reference internal" href="email.policy.html#email.policy.compat32" title="email.policy.compat32"><code class="xref py py-const docutils literal notranslate"><span class="pre">compat32</span></code></a> policy does not support these methods963and should not be used with <code class="xref py py-class docutils literal notranslate"><span class="pre">EmailMessage</span></code>.</p>964</aside>965</aside>966</section>967 968 969            <div class="clearer"></div>970          </div>971        </div>972      </div>973      <div class="sphinxsidebar" role="navigation" aria-label="Main">974        <div class="sphinxsidebarwrapper">975  <div>976    <h4>Previous topic</h4>977    <p class="topless"><a href="email.html"978                          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>979  </div>980  <div>981    <h4>Next topic</h4>982    <p class="topless"><a href="email.parser.html"983                          title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.parser</span></code>: Parsing email messages</a></p>984  </div>985  <script>986    document.addEventListener('DOMContentLoaded', () => {987        const title = document.querySelector('meta[property="og:title"]').content;988        const elements = document.querySelectorAll('.improvepage');989        const pageurl = window.location.href.split('?')[0];990        elements.forEach(element => {991            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));992            url.searchParams.set('pagetitle', title);993            url.searchParams.set('pageurl', pageurl);994            url.searchParams.set('pagesource', "library/email.message.rst");995            element.href = url.toString();996        });997    });998  </script>999  <div role="note" aria-label="source link">1000    <h3>This page</h3>1001    <ul class="this-page-menu">1002      <li><a href="../bugs.html">Report a bug</a></li>1003      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>1004      <li>1005        <a href="https://github.com/python/cpython/blob/main/Doc/library/email.message.rst?plain=1"1006            rel="nofollow">Show source1007        </a>1008      </li>1009      1010    </ul>1011  </div>1012        </div>1013<div id="sidebarbutton" title="Collapse sidebar">1014<span>«</span>1015</div>1016 1017      </div>1018      <div class="clearer"></div>1019    </div>  1020    <div class="related" role="navigation" aria-label="Related">1021      <h3>Navigation</h3>1022      <ul>1023        <li class="right" style="margin-right: 10px">1024          <a href="../genindex.html" title="General Index"1025             >index</a></li>1026        <li class="right" >1027          <a href="../py-modindex.html" title="Python Module Index"1028             >modules</a> |</li>1029        <li class="right" >1030          <a href="email.parser.html" title="email.parser: Parsing email messages"1031             >next</a> |</li>1032        <li class="right" >1033          <a href="email.html" title="email — An email and MIME handling package"1034             >previous</a> |</li>1035 1036          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>1037          <li><a href="https://www.python.org/">Python</a> &#187;</li>1038          <li class="switchers">1039            <div class="language_switcher_placeholder"></div>1040            <div class="version_switcher_placeholder"></div>1041          </li>1042          <li>1043              1044          </li>1045    <li id="cpython-language-and-version">1046      <a href="../index.html">3.15.0a6 Documentation</a> &#187;1047    </li>1048 1049          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>1050          <li class="nav-item nav-item-2"><a href="netdata.html" >Internet Data Handling</a> &#187;</li>1051          <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> &#187;</li>1052        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">email.message</span></code>: Representing an email message</a></li>1053                <li class="right">1054                    1055 1056    <div class="inline-search" role="search">1057        <form class="inline-search" action="../search.html" method="get">1058          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">1059          <input type="submit" value="Go">1060        </form>1061    </div>1062                     |1063                </li>1064            <li class="right">1065<label class="theme-selector-label">1066    Theme1067    <select class="theme-selector" oninput="activateTheme(this.value)">1068        <option value="auto" selected>Auto</option>1069        <option value="light">Light</option>1070        <option value="dark">Dark</option>1071    </select>1072</label> |</li>1073            1074      </ul>1075    </div>  1076    <div class="footer">1077    &copy; <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.1078    <br>1079    This page is licensed under the Python Software Foundation License Version 2.1080    <br>1081    Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.1082    <br>1083    1084      See <a href="/license.html">History and License</a> for more information.<br>1085    1086    1087    <br>1088 1089    The Python Software Foundation is a non-profit corporation.1090<a href="https://www.python.org/psf/donations/">Please donate.</a>1091<br>1092    <br>1093      Last updated on Mar 10, 2026 (08:58 UTC).1094    1095      <a href="/bugs.html">Found a bug</a>?1096    1097    <br>1098 1099    Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1100    </div>1101 1102  </body>1103</html>