rust/lettre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dca316deae6fffc1d5363f13fd45c7ca5e26f19a
lettre/docs/sending-messages/smtp/index.html
Alexis Mousset bae531e264 Add logo
2017-05-26 00:15:56 +02:00

493 lines
21 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en" class="js csstransforms3d">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
<meta name="generator" content="Hugo 0.20.7" />
<meta name="description" content="Documentation for the Lettre mailer in Rust">
<meta name="author" content="Alexis Mousset">
<link rel="shortcut icon" href="/images/favicon.png" type="image/x-icon" />
<title>SMTP transport</title>
<link href="https://lettre.github.io/lettre//css/nucleus.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/font-awesome.min.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/hybrid.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/featherlight.min.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/perfect-scrollbar.min.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/horsey.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/theme.css" rel="stylesheet">
<link href="https://lettre.github.io/lettre//css/hugo-theme.css" rel="stylesheet">
<script src="https://lettre.github.io/lettre//js/jquery-2.x.min.js"></script>
<style type="text/css">:root #header + #content > #left > #rlblock_left
{display:none !important;}</style>
</head>
<body class="" data-url="/lettre/sending-messages/smtp/">
<nav id="sidebar">
<div id="header-wrapper">
<div id="header">
<img src="../images/logo50.png" />
</div>
<div class="searchbox">
<label for="search-by"><i class="fa fa-search"></i></label>
<input data-search-input id="search-by" type="text" placeholder="Search">
<span data-search-clear=""><i class="fa fa-close"></i></span>
</div>
<script type="text/javascript" src="https://lettre.github.io/lettre//js/lunr.min.js"></script>
<script type="text/javascript" src="https://lettre.github.io/lettre//js/horsey.js"></script>
<script type="text/javascript">
var baseurl = "https:\/\/lettre.github.io\/lettre\/";
</script>
<script type="text/javascript" src="https://lettre.github.io/lettre//js/search.js"></script>
</div>
<div class="highlightable">
<ul class="topics">
<li class="dd-item " data-nav-id="/lettre/getting-started/">
<a href="/lettre/getting-started/">
<span>
<b>1. </b>
Getting started
</span>
</a>
<ul>
<li class="dd-item " data-nav-id="/lettre/getting-started/intro/">
<a href="/lettre/getting-started/intro/">
<span>Introduction </i></span>
</a>
</li>
</ul>
</li>
<li class="dd-item " data-nav-id="/lettre/creating-messages/">
<a href="/lettre/creating-messages/">
<span>
<b>2. </b>
Creating messages
</span>
</a>
</li>
<li class="dd-item parent" data-nav-id="/lettre/sending-messages/">
<a href="/lettre/sending-messages/">
<span>
<b>3. </b>
Sending messages
</span>
</a>
<ul>
<li class="dd-item " data-nav-id="/lettre/sending-messages/intro/">
<a href="/lettre/sending-messages/intro/">
<span>Introduction </i></span>
</a>
</li>
<li class="dd-item active" data-nav-id="/lettre/sending-messages/smtp/">
<a href="/lettre/sending-messages/smtp/">
<span>SMTP transport </i></span>
</a>
</li>
<li class="dd-item " data-nav-id="/lettre/sending-messages/sendmail/">
<a href="/lettre/sending-messages/sendmail/">
<span>Sendmail transport </i></span>
</a>
</li>
<li class="dd-item " data-nav-id="/lettre/sending-messages/file/">
<a href="/lettre/sending-messages/file/">
<span>File transport </i></span>
</a>
</li>
<li class="dd-item " data-nav-id="/lettre/sending-messages/stub/">
<a href="/lettre/sending-messages/stub/">
<span>Stub transport </i></span>
</a>
</li>
</ul>
</li>
</ul>
<hr>
<section id="footer">
<p>Built with <a href="https://github.com/matcornic/hugo-theme-learn"><i class="fa fa-heart"></i></a> from <a href="http://getgrav.org">Grav</a> and <a href="http://gohugo.io/">Hugo</a></p>
</section>
</div>
</nav>
<section id="body">
<div id="overlay"></div>
<div class="padding highlightable">
<div id="top-bar">
<div id="top-github-link">
<a class="github-link" href="https://github.com/lettre/lettre/edit/master/website/content/sending-messages/smtp.md" target="blank">
<i class="fa fa-code-fork"></i>
Edit this page
</a>
</div>
<div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
<span id="sidebar-toggle-span">
<a href="#" id="sidebar-toggle" data-sidebar-toggle="">
<i class="fa fa-bars"></i>
</a>
</span>
<span id="toc-menu"><a href=""><i class="fa fa-list-alt"></i></a></span>
<a href="/lettre/sending-messages/" itemprop="url"><span itemprop="title">Sending messages</span></a> <i class="fa fa-angle-right"></i>
<span itemprop="title"> SMTP transport</span>
</div>
<div class="progress">
<div class="wrapper">
<nav id="TableOfContents">
<ul>
<li>
<ul>
<li>
<ul>
<li>
<ul>
<li><a href="#simple-example">Simple example</a></li>
<li><a href="#complete-example">Complete example</a></li>
<li><a href="#lower-level">Lower level</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</nav>
</div>
</div>
</div>
<div id="body-inner">
<h1>SMTP transport</h1>
<p>This transport uses the SMTP protocol to send emails over the network (locally or remotely).</p>
<p>It is desinged to be:</p>
<ul>
<li>Secured: email are encrypted by default</li>
<li>Modern: Unicode support for email content and sender/recipient adresses when compatible</li>
<li>Fast: supports tcp connection reuse</li>
</ul>
<p>This client is designed to send emails to a relay server, and should <em>not</em> be used to send
emails directly to the destination.</p>
<p>The relay server can be the local email server, a specific host or a third-party service.</p>
<h4 id="simple-example">Simple example</h4>
<p>This is the most basic example of usage:</p>
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span></span><span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">{SimpleSendableEmail, EmailTransport};</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">SmtpTransportBuilder;</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">SecurityLevel;</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> email </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> SimpleSendableEmail</span>::<span style="color: #f8f8f2">new(</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;user@localhost&quot;</span><span style="color: #f8f8f2">,</span>
<span style="color: #f8f8f2"> vec</span><span style="color: #f92672">!</span><span style="color: #f8f8f2">[</span><span style="color: #e6db74">&quot;root@localhost&quot;</span><span style="color: #f8f8f2">],</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;message_id&quot;</span><span style="color: #f8f8f2">,</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;Hello world&quot;</span><span style="color: #f8f8f2"></span>
<span style="color: #f8f8f2"> );</span>
<span style="color: #75715e">// Open a local connection on port 25</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> </span><span style="color: #66d9ef">mut</span><span style="color: #f8f8f2"> mailer </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"></span>
<span style="color: #f8f8f2">SmtpTransportBuilder</span>::<span style="color: #f8f8f2">localhost().unwrap().security_level(SecurityLevel</span>::<span style="color: #f8f8f2">Opportunistic).build();</span>
<span style="color: #75715e">// Send the email</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> result </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> mailer.send(email);</span>
<span style="color: #f8f8f2">assert</span><span style="color: #f92672">!</span><span style="color: #f8f8f2">(result.is_ok());</span>
</pre></div>
<h4 id="complete-example">Complete example</h4>
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span></span><span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">{SecurityLevel, SmtpTransport,</span>
<span style="color: #f8f8f2">SmtpTransportBuilder};</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">authentication</span>::<span style="color: #f8f8f2">Mechanism;</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">SUBMISSION_PORT;</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">{SimpleSendableEmail, EmailTransport};</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> email </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> SimpleSendableEmail</span>::<span style="color: #f8f8f2">new(</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;user@localhost&quot;</span><span style="color: #f8f8f2">,</span>
<span style="color: #f8f8f2"> vec</span><span style="color: #f92672">!</span><span style="color: #f8f8f2">[</span><span style="color: #e6db74">&quot;root@localhost&quot;</span><span style="color: #f8f8f2">],</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;message_id&quot;</span><span style="color: #f8f8f2">,</span>
<span style="color: #f8f8f2"> </span><span style="color: #e6db74">&quot;Hello world&quot;</span><span style="color: #f8f8f2"></span>
<span style="color: #f8f8f2"> );</span>
<span style="color: #75715e">// Connect to a remote server on a custom port</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> </span><span style="color: #66d9ef">mut</span><span style="color: #f8f8f2"> mailer </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> SmtpTransportBuilder</span>::<span style="color: #f8f8f2">new((</span><span style="color: #e6db74">&quot;server.tld&quot;</span><span style="color: #f8f8f2">,</span>
<span style="color: #f8f8f2">SUBMISSION_PORT)).unwrap()</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Set the name sent during EHLO/HELO, default is `localhost`</span>
<span style="color: #f8f8f2"> .hello_name(</span><span style="color: #e6db74">&quot;my.hostname.tld&quot;</span><span style="color: #f8f8f2">)</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Add credentials for authentication</span>
<span style="color: #f8f8f2"> .credentials(</span><span style="color: #e6db74">&quot;username&quot;</span><span style="color: #f8f8f2">, </span><span style="color: #e6db74">&quot;password&quot;</span><span style="color: #f8f8f2">)</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Specify a TLS security level. You can also specify an SslContext with</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// .ssl_context(SslContext::Ssl23)</span>
<span style="color: #f8f8f2"> .security_level(SecurityLevel</span>::<span style="color: #f8f8f2">AlwaysEncrypt)</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Enable SMTPUTF8 if the server supports it</span>
<span style="color: #f8f8f2"> .smtp_utf8(</span><span style="color: #66d9ef">true</span><span style="color: #f8f8f2">)</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Configure expected authentication mechanism</span>
<span style="color: #f8f8f2"> .authentication_mechanism(Mechanism</span>::<span style="color: #f8f8f2">CramMd5)</span>
<span style="color: #f8f8f2"> </span><span style="color: #75715e">// Enable connection reuse</span>
<span style="color: #f8f8f2"> .connection_reuse(</span><span style="color: #66d9ef">true</span><span style="color: #f8f8f2">).build();</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> result_1 </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> mailer.send(email.clone());</span>
<span style="color: #f8f8f2">assert</span><span style="color: #f92672">!</span><span style="color: #f8f8f2">(result_1.is_ok());</span>
<span style="color: #75715e">// The second email will use the same connection</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> result_2 </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> mailer.send(email);</span>
<span style="color: #f8f8f2">assert</span><span style="color: #f92672">!</span><span style="color: #f8f8f2">(result_2.is_ok());</span>
<span style="color: #75715e">// Explicitly close the SMTP transaction as we enabled connection reuse</span>
<span style="color: #f8f8f2">mailer.close();</span>
</pre></div>
<h4 id="lower-level">Lower level</h4>
<p>You can also send commands, here is a simple email transaction without
error handling:</p>
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span></span><span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">SMTP_PORT;</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">client</span>::<span style="color: #f8f8f2">Client;</span>
<span style="color: #66d9ef">use</span><span style="color: #f8f8f2"> lettre</span>::<span style="color: #f8f8f2">smtp</span>::<span style="color: #f8f8f2">client</span>::<span style="color: #f8f8f2">net</span>::<span style="color: #f8f8f2">NetworkStream;</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> </span><span style="color: #66d9ef">mut</span><span style="color: #f8f8f2"> email_client</span>: <span style="color: #a6e22e">Client</span><span style="color: #f92672">&lt;</span><span style="color: #f8f8f2">NetworkStream</span><span style="color: #f92672">&gt;</span><span style="color: #f8f8f2"> </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> Client</span>::<span style="color: #f8f8f2">new();</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.connect(</span><span style="color: #f92672">&amp;</span><span style="color: #f8f8f2">(</span><span style="color: #e6db74">&quot;localhost&quot;</span><span style="color: #f8f8f2">, SMTP_PORT), None);</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.ehlo(</span><span style="color: #e6db74">&quot;my_hostname&quot;</span><span style="color: #f8f8f2">);</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.mail(</span><span style="color: #e6db74">&quot;user@example.com&quot;</span><span style="color: #f8f8f2">, None);</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.rcpt(</span><span style="color: #e6db74">&quot;user@example.org&quot;</span><span style="color: #f8f8f2">);</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.data();</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.message(</span><span style="color: #e6db74">&quot;Test email&quot;</span><span style="color: #f8f8f2">);</span>
<span style="color: #66d9ef">let</span><span style="color: #f8f8f2"> _ </span><span style="color: #f92672">=</span><span style="color: #f8f8f2"> email_client.quit();</span>
</pre></div>
</div>
</div>
<div id="navigation">
<a class="nav nav-prev" href="/lettre/sending-messages/intro/"> <i class="fa fa-chevron-left"></i></a>
<a class="nav nav-next" href="/lettre/sending-messages/sendmail/" style="margin-right: 0px;"><i class="fa fa-chevron-right"></i></a>
</div>
</section>
<div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
<div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
</div>
<script src="https://lettre.github.io/lettre//js/clipboard.min.js"></script>
<script src="https://lettre.github.io/lettre//js/perfect-scrollbar.min.js"></script>
<script src="https://lettre.github.io/lettre//js/perfect-scrollbar.jquery.min.js"></script>
<script src="https://lettre.github.io/lettre//js/jquery.sticky-kit.min.js"></script>
<script src="https://lettre.github.io/lettre//js/featherlight.min.js"></script>
<script src="https://lettre.github.io/lettre//js/html5shiv-printshiv.min.js"></script>
<script src="https://lettre.github.io/lettre//js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
<script src="https://lettre.github.io/lettre//js/modernizr.custom.71422.js"></script>
<script src="https://lettre.github.io/lettre//js/learn.js"></script>
<script src="https://lettre.github.io/lettre//js/hugo-learn.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink