File: //usr/share/doc/python3-aiosmtpd/html/concepts.html
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Concepts — aiosmtpd 1.4.4.post2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=86f27845" />
<link rel="stylesheet" type="text/css" href="_static/aiosmtpd.css?v=4cc6bf70" />
<script src="_static/jquery.js?v=8dae8fb0"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=ad49bbf5"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Command line usage" href="cli.html" />
<link rel="prev" title="Introduction" href="intro.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
aiosmtpd
</a>
<div class="version">
1.4.4.post2
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Concepts</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#sessions-and-envelopes">Sessions and envelopes</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#session">Session</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#Session"><code class="docutils literal notranslate"><span class="pre">Session</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#envelope">Envelope</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#Envelope"><code class="docutils literal notranslate"><span class="pre">Envelope</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cli.html">Command line usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="controller.html">Programmatic usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="smtp.html">The SMTP Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="lmtp.html">The LMTP class</a></li>
<li class="toctree-l1"><a class="reference internal" href="handlers.html">Handlers</a></li>
<li class="toctree-l1"><a class="reference internal" href="auth.html">Authentication System</a></li>
<li class="toctree-l1"><a class="reference internal" href="proxyprotocol.html">PROXY Protocol Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="migrating.html">Migrating from smtpd to aiosmtpd</a></li>
<li class="toctree-l1"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="manpage.html">aiosmtpd</a></li>
<li class="toctree-l1"><a class="reference internal" href="NEWS.html">NEWS for aiosmtpd</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">aiosmtpd</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Concepts</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/concepts.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="concepts">
<h1>Concepts<a class="headerlink" href="#concepts" title="Link to this heading"></a></h1>
<p>There are two general ways you can run the SMTP server, via the
<a class="reference internal" href="cli.html#cli"><span class="std std-ref">command line</span></a> or <a class="reference internal" href="controller.html#controller"><span class="std std-ref">programmatically</span></a>.</p>
<p>There are several dimensions in which you can extend the basic functionality
of the SMTP server. You can implement an <em>event handler</em> which uses well
defined <a class="reference internal" href="handlers.html#hooks"><span class="std std-ref">handler hooks</span></a> that are called during the various steps
in the SMTP dialog. If such a hook is implemented, it assumes responsibility
for the status messages returned to the client.</p>
<p>You can also <a class="reference internal" href="smtp.html#subclass"><span class="std std-ref">subclass</span></a> the core <code class="docutils literal notranslate"><span class="pre">SMTP</span></code> class to implement
new commands, or change the semantics of existing commands.</p>
<p>For example, if you wanted to print the received message on the console, you
could implement a handler that hooks into the <code class="docutils literal notranslate"><span class="pre">DATA</span></code> command. The contents
of the message will be available on one of the hook’s arguments, and your
handler could print this content to stdout.</p>
<p>On the other hand, if you wanted to implement an SMTP-like server that adds a
new command called <code class="docutils literal notranslate"><span class="pre">PING</span></code>, you would do this by subclassing <code class="docutils literal notranslate"><span class="pre">SMTP</span></code>, adding
a method that implements whatever semantics for <code class="docutils literal notranslate"><span class="pre">PING</span></code> that you want.</p>
<section id="sessions-and-envelopes">
<span id="id1"></span><h2>Sessions and envelopes<a class="headerlink" href="#sessions-and-envelopes" title="Link to this heading"></a></h2>
<p>Two classes are used during the SMTP dialog with clients. Instances of these
are passed to the handler hooks.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Handler Hooks MAY add new attributes to these classes for inter-hook coordination.</p>
</div>
<section id="session">
<h3>Session<a class="headerlink" href="#session" title="Link to this heading"></a></h3>
<p>The session represents the state built up during a client’s socket connection
to the server. Each time a client connects to the server, a new session
object is created.</p>
<dl class="py class">
<dt class="sig sig-object py" id="Session">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Session</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">loop</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#Session" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>loop</strong> – asyncio event loop currently running <code class="xref py py-class docutils literal notranslate"><span class="pre">SMTP</span></code>.</p>
</dd>
</dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.peer">
<span class="sig-name descname"><span class="pre">peer</span></span><a class="headerlink" href="#Session.peer" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute will contain the transport’s socket’s
<a class="reference external" href="https://docs.python.org/3/library/asyncio-protocol.html?highlight=peername#asyncio.BaseTransport.get_extra_info"><code class="docutils literal notranslate"><span class="pre">peername</span></code></a> value.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.ssl">
<span class="sig-name descname"><span class="pre">ssl</span></span><a class="headerlink" href="#Session.ssl" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute will contain some extra information,
as a dictionary, from the <code class="docutils literal notranslate"><span class="pre">asyncio.sslproto.SSLProtocol</span></code> instance.
This dictionary provides additional information about the connection.
It contains implementation-specific information so its contents may
change, but it should roughly correspond to the information available
through <code class="xref py py-meth docutils literal notranslate"><span class="pre">asyncio.BaseTransport.get_extra_info()</span></code></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.host_name">
<span class="sig-name descname"><span class="pre">host_name</span></span><a class="headerlink" href="#Session.host_name" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute will contain the host name argument
as seen in the <code class="docutils literal notranslate"><span class="pre">HELO</span></code> or <code class="docutils literal notranslate"><span class="pre">EHLO</span></code> (or for <a class="reference internal" href="lmtp.html#lmtp"><span class="std std-ref">LMTP</span></a>, the
<code class="docutils literal notranslate"><span class="pre">LHLO</span></code>) command.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.extended_smtp">
<span class="sig-name descname"><span class="pre">extended_smtp</span></span><a class="headerlink" href="#Session.extended_smtp" title="Link to this definition"></a></dt>
<dd><p>Defaulting to False, this flag will be True when the <code class="docutils literal notranslate"><span class="pre">EHLO</span></code> greeting
was seen, indicating <span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc1869.html"><strong>ESMTP</strong></a>.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.loop">
<span class="sig-name descname"><span class="pre">loop</span></span><a class="headerlink" href="#Session.loop" title="Link to this definition"></a></dt>
<dd><p>This is the asyncio event loop instance.</p>
<p><a class="reference internal" href="handlers.html#hooks"><span class="std std-ref">Handler Hooks</span></a> can utilize this if needed,
for instance invoking <code class="xref py py-meth docutils literal notranslate"><span class="pre">call_later()</span></code> to set some timers.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.login_data">
<span class="sig-name descname"><span class="pre">login_data</span></span><a class="headerlink" href="#Session.login_data" title="Link to this definition"></a></dt>
<dd><p>Contains the login information gathered during the <code class="docutils literal notranslate"><span class="pre">AUTH</span></code> procedure.
If it contains <code class="docutils literal notranslate"><span class="pre">None</span></code>, that means authentication has not taken place
or has failed.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This is the “legacy” login_data,
populated only if <code class="xref py py-attr docutils literal notranslate"><span class="pre">auth_callback</span></code> parameter is set.</p>
</div>
<div class="deprecated">
<p><span class="versionmodified deprecated">Deprecated since version 1.3: </span>This attribute <strong>will be removed in version 2.0</strong>.</p>
</div>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.auth_data">
<span class="sig-name descname"><span class="pre">auth_data</span></span><a class="headerlink" href="#Session.auth_data" title="Link to this definition"></a></dt>
<dd><p>Contains the authentication data returned by
the <code class="xref py py-attr docutils literal notranslate"><span class="pre">authenticator</span></code> callback.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Session.authenticated">
<span class="sig-name descname"><span class="pre">authenticated</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">bool</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#Session.authenticated" title="Link to this definition"></a></dt>
<dd><p>A tri-state flag indicating status of authentication:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> := Authentication has not been performed</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">False</span></code> := Authentication has been performed, but failed</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">True</span></code> := Authentication has been performed, and succeeded</p></li>
</ul>
</div></blockquote>
</dd></dl>
</dd></dl>
</section>
<section id="envelope">
<h3>Envelope<a class="headerlink" href="#envelope" title="Link to this heading"></a></h3>
<p>The envelope represents state built up during the client’s SMTP dialog. Each
time the protocol state is reset, a new envelope is created. E.g. when the
SMTP <code class="docutils literal notranslate"><span class="pre">RSET</span></code> command is sent, the state is reset and a new envelope is
created. A new envelope is also created after the <code class="docutils literal notranslate"><span class="pre">DATA</span></code> command is
completed, or in certain error conditions as mandated by <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5321.html"><strong>RFC 5321</strong></a>.</p>
<dl class="py class">
<dt class="sig sig-object py" id="Envelope">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Envelope</span></span><a class="headerlink" href="#Envelope" title="Link to this definition"></a></dt>
<dd><dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.mail_from">
<span class="sig-name descname"><span class="pre">mail_from</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="headerlink" href="#Envelope.mail_from" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute holds the email address given in the
<code class="docutils literal notranslate"><span class="pre">MAIL</span> <span class="pre">FROM</span></code> command.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.mail_options">
<span class="sig-name descname"><span class="pre">mail_options</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#Envelope.mail_options" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute contains a list of any ESMTP mail
options provided by the client, such as those passed in by
<code class="xref py py-meth docutils literal notranslate"><span class="pre">smtplib.SMTP.sendmail()</span></code></p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.content">
<span class="sig-name descname"><span class="pre">content</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">AnyStr</span></em><a class="headerlink" href="#Envelope.content" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute will contain the contents of the
message as provided by the <code class="docutils literal notranslate"><span class="pre">DATA</span></code> command. If the <code class="docutils literal notranslate"><span class="pre">decode_data</span></code>
parameter to the <code class="docutils literal notranslate"><span class="pre">SMTP</span></code> constructor was True, then this attribute will
contain the UTF-8 decoded string, otherwise it will contain the raw
bytes.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.original_content">
<span class="sig-name descname"><span class="pre">original_content</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">bytes</span></em><a class="headerlink" href="#Envelope.original_content" title="Link to this definition"></a></dt>
<dd><p>Defaulting to None, this attribute will contain the contents of the
message as provided by the <code class="docutils literal notranslate"><span class="pre">DATA</span></code> command. Unlike the <a class="reference internal" href="#Envelope.content" title="Envelope.content"><code class="xref py py-attr docutils literal notranslate"><span class="pre">content</span></code></a>
attribute, this attribute will always contain the raw bytes.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.rcpt_tos">
<span class="sig-name descname"><span class="pre">rcpt_tos</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#Envelope.rcpt_tos" title="Link to this definition"></a></dt>
<dd><p>Defaulting to the empty list, this attribute will contain a list of the
email addresses provided in the <code class="docutils literal notranslate"><span class="pre">RCPT</span> <span class="pre">TO</span></code> commands.</p>
</dd></dl>
<dl class="py attribute">
<dt class="sig sig-object py" id="Envelope.rcpt_options">
<span class="sig-name descname"><span class="pre">rcpt_options</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">List</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#Envelope.rcpt_options" title="Link to this definition"></a></dt>
<dd><p>Defaulting to the empty list, this attribute will contain the list of
any recipient options provided by the client, such as those passed in by
<code class="xref py py-meth docutils literal notranslate"><span class="pre">smtplib.SMTP.sendmail()</span></code></p>
</dd></dl>
</dd></dl>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="intro.html" class="btn btn-neutral float-left" title="Introduction" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="cli.html" class="btn btn-neutral float-right" title="Command line usage" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2015-2024, The aiosmtpd Developers.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>