view release on metacpan or  search on metacpan

devdata/http_advent.perldancer.org_2018_17  view on Meta::CPAN

</li>
</ul>
</div>


<div id="content">
<div class="pod-document"><h1><a name="dancer_and_email"></a>Dancer and Email</h1>

<p>Web applications regularly need to send email to its users, e.g. receipts or password reset links. 
The <a href="https://metacpan.org/pod/Dancer2::Plugin::Email">Email</a> plugin for Dancer2 simplifies this task by
providing the <code>email</code> keyword and a sane default configuration.</p>
<p>So the unavoidable "Hello world" example would look like:</p>
<pre class="prettyprint">email {
    from =&gt; 'foo@perl.dance',
    to =&gt; 'bar@perl.dance',
    subject =&gt; 'Hello world',
    text =&gt; 'Welcome to the dancefloor!',
};</pre>

<p>The more common case would be to use a template from your web application and turn it into a HTML email.</p>
<p>Instead of using the <code>template</code> keyword to return the HTML from your route to the browser, you generate HTML with a specific layout,
store in a variable and send the email.</p>
<pre class="prettyprint">post '/welcome' =&gt; {
      
    my $html = template $template, $tokens, { layout =&gt; 'email' };

    email {
        from =&gt; 'foo@perl.dance',
        to =&gt; 'bar@perl.dance',
        subject =&gt; 'Welcome to the dancefloor!',
        type =&gt; 'html',
        body =&gt; $html,
    }

    redirect '/home';
}</pre>

<h2><a name="utf_8"></a>UTF-8</h2>

<p>Take care to encode your content and mail headers if it may contain UTF-8 characters.
It might even look good in your email client if you don't do this, but not necessarily for other ones.</p>
<pre class="prettyprint">email {
    from =&gt; 'foo@perl.dance',
    to =&gt; 'bar@perl.dance',
    subject =&gt; encode('MIME-Header', '&#xdc;ber uns'),
    type =&gt; 'html',
    body =&gt; encode('UTF-8',
        'Die Geschichte unseres Projekts begann mit dem franz&#xf6;sischen Entwicker Alexis Sukrieh ...'),
};</pre>

<h2><a name="inline_images"></a>Inline images</h2>

<p>You can simply deliver emails with links to images, but usually email clients would not load them without user interaction.
It is possible though to attached the images to the email and reference them in the email body with a custom HTML tag:</p>
<pre class="prettyprint">    email {
        from      =&gt; 'foo@perl.dance',
        to        =&gt; 'bar@perl.dance',
        subject   =&gt; 'Welcome to the dancefloor!',
        body      =&gt; q{&lt;p&gt;Image embedded: &lt;img src="cid:mycid"/&gt;&lt;/p&gt;},
        type      =&gt; 'html',
        attach    =&gt; [ { Id =&gt; 'mycid', Path =&gt; '/dancefloor/dcr-header-logo.png' }],
        multipart =&gt; 'related'
};</pre>

<h2><a name="providing_plain_text_part"></a>Providing plain text part</h2>

<p><a href="https://metacpan.org/pod/HTML::FormatText::WithLinks">HTML::FormatText::WithLinks</a> makes it easy to provide a plain text version
of your HTML email:</p>
<pre class="prettyprint">my $html = template $template, $tokens, { layout =&gt; 'email' };

my $f    = HTML::FormatText::WithLinks-&gt;new;
my $text = $f-&gt;parse($html);

email {
    from =&gt; 'foo@perl.dance',
    to =&gt; 'bar@perl.dance',
    subject =&gt; 'Welcome to the dancefloor!',
    body   =&gt; $text,
    attach =&gt; {
        Data     =&gt; $html,
        Type     =&gt; "text/html"
    },
    multipart =&gt; 'alternative',
};</pre>

<h2><a name="configuration"></a>Configuration</h2>

<h3><a name="transports"></a>Transports</h3>

<p>Under the hood the plugin uses <a href="https://metacpan.org/pod/Email::Sender">Email::Sender</a>, so you can utilize its transports instead of the "sendmail" one (local mail server).</p>
<p>This is just a matter of adjusting your configuration:</p>
<pre class="prettyprint">plugins:
  Email:
    transport:
      SMTP:
        ssl: 1
        host: 'mail.perl.dance'
        port: 465
        sasl_username: 'foo@perl.dance'
        sasl_password: 'nevairbe'</pre>

<p>In development you want to <b>prevent</b> email going out to <b>real users</b>.</p>
<p>This can be done with the <a href="https://metacpan.org/pod/Email::Sender::Transport::Redirect">Redirect</a> transport:</p>
<pre class="prettyprint">plugins:
  Email:
    transport:
      Sendmail:
        redirect_address: racke@perl.dance</pre>

<p>All email will be send to the specificied address, but with extra headers added with the original recipients:</p>
<pre class="prettyprint">X-Intercepted-To: "Bar" &lt;bar@perl.dance&gt;
X-Intercepted-Cc: "Baz" &lt;baz@perl.dance&gt;</pre>

<p>Note: it's the presence of the <code>redirect_address</code> parameter which tells the
plugin you want mails redirected to that address, this will work with whatever
transport you wish to use.</p>
<h3><a name="preseed_headers"></a>Preseed headers</h3>

<p>If you have a standard email address and/or you want to have extra email headers, you can specify these in the
configuration as well:</p>
<pre class="prettyprint">plugins: