Dancer...::Email(3pm)

💌 NAME

okay bestie, gather round — this is Dancer::Plugin::Email, and it does exactly what it says on the tin: simple email sending for Dancer applications. that's the whole vibe. 💖

---

✨ VERSION

version 1.0400 — that's the one you're getting, no cap.

---

🌸 SYNOPSIS

here's the whole thing in one glamorous little snapshot:

    use Dancer;
    use Dancer::Plugin::Email;

    post '/contact' => sub {
        email {
            from    => 'bob@foo.com',
            to      => 'sue@foo.com',
            subject => 'allo',
            body    => 'Dear Sue, ...',
            attach  => '/path/to/attachment',
        };
    };

like… that's it. that's the post. 💅

---

🦋 DESCRIPTION

so this plugin's whole goal in life is making emails from Dancer apps as simple as humanly possible. it does its magic using Email::Sender under the hood 🧚. and here's the slay part: in a lot of cases you literally need no configuration at all. for example, if your app is hosted on a unix-like server with sendmail installed, calling email() will just… do the right thing. iconic behavior honestly. ✨

⚠️ IMPORTANT: Version 1.x of this module is not backwards compatible with the 0.x versions. 💀

okay let me explain the lore. this module was originally built on Email::Stuff, which was built on Email::Send, which has been deprecated in favor of Email::Sender. so versions 1.x and on got refactored to use Email::Sender. the author tried to keep the interface the same as much as possible 🫶 — and the main difference is the configuration. if there are features missing that you were using in older versions, then please let them know by creating an issue on github <https://github.com/ironcamel/Dancer-Plugin-Email>. (yes, that URL is in the original, keep it, it's important!)

---

🎀 FUNCTIONS

by default this module exports the single function email. one function. one icon. 👑

💌 email

this function sends an email. it takes a single argument: a hashref of parameters. default values for those parameters can be provided in the headers section of the CONFIGURATION. and the way it works is: parameters you hand to this function override the corresponding configuration values whenever there's any overlap. bestie, watch out though — an exception is thrown if sending the email fails, so wrapping your calls to email with try/catch is recommended. fr fr. 😭

    use Dancer;
    use Dancer::Plugin::Email;
    use Try::Tiny;

    post '/contact' => sub {
        try {
            email {
                sender  => 'bounces-here@foo.com', # optional
                from    => 'bob@foo.com',
                to      => 'sue@foo.com, jane@foo.com',
                bcc     => 'sam@foo.com',
                subject => 'allo',
                body    => 'Dear Sue, ...<img src="cid:blabla">',
                multipart => 'related', # optional, see below
                attach  => [
                    '/path/to/attachment1',
                    '/path/to/attachment2',
                    {
                        Path => "/path/to/attachment3",
                        # Path is required when passing a hashref.
                        # See Mime::Entity for other optional values.
                        Id => "blabla",
                    }
                ],
                type    => 'html', # can be 'html' or 'plain'
                # Optional extra headers
                headers => {
                    "X-Mailer"          => 'This fine Dancer application',
                    "X-Accept-Language" => 'en',
                }
            };
        } catch {
            error "Could not send email: $_";
        };
    };

look at that. look at the little try/catch being all responsible. we love a safety queen. 🫶

---

🌈 CONFIGURATION

no configuration is necessarily required. Email::Sender::Simple tries to make a good guess about how to send the message — it will usually try to use the sendmail program on unix-like systems, and SMTP on Windows. it's giving "trust me, I got this". 😌

but you may explicitly configure a transport in your configuration. only one transport may be configured. for documentation for the parameters of the transport, see the corresponding Email::Sender::Transport::* module. for example, the parameters available for the SMTP transport are documented here "ATTRIBUTES" in Email::Sender::Transport::SMTP.

you may also provide default headers in the configuration:

    plugins:
      Email:
        # Set default headers (OPTIONAL)
        headers:
          sender: 'bounces-here@foo.com'
          from: 'bob@foo.com'
          subject: 'default subject'
          X-Mailer: 'MyDancer 1.0'
          X-Accept-Language: 'en'
        # Explicity set a transport (OPTIONAL)
        transport:
          Sendmail:
            sendmail: '/usr/sbin/sendmail'

example configuration for sending mail via Gmail 📧:

    plugins:
      Email:
        transport:
          SMTP:
            ssl: 1
            host: 'smtp.gmail.com'
            port: 465
            sasl_username: 'bob@gmail.com'
            sasl_password: 'secret'

use the Sendmail transport using the sendmail program in the system path:

    plugins:
      Email:
        transport:
          Sendmail:

use the Sendmail transport with an explicit path to the sendmail program:

    plugins:
      Email:
        transport:
          Sendmail:
            sendmail: '/usr/sbin/sendmail'

🖼️ Multipart messages

okay so you can embed images in HTML messages this way: first, set the type to html. then pass the attachments as hashrefs, setting Path and Id. in the HTML body, refer to the attachment using the Id, prepending cid: in the src attribute. this works for popular webmail clients like Gmail and OE 👑, but is not enough for Thunderbird, which wants a multipart/related mail, not the default multipart/mixed. you can fix this by adding the multipart parameter set to related, which sets the desired subtype when you pass attachments. iykyk. 🦋

example:

  email {
         from    => $from,
         to      => $to,
         subject => $subject,
         body    => q{<p>Image embedded: <img src="cid:mycid"/></p>},
         type    => 'html',
         attach  => [ { Id => 'mycid', Path => '/path/to/file' }],
         multipart => 'related'
        };

the attach value accepts either a single attachment or an arrayref of attachment. each attachment may be a scalar, with the path of the file to attach, or an hashref — in which case the hashref is passed to the Mime::Entity's attach method. 🌸

---

💖 CONTRIBUTORS

the ones who helped make this happen, absolute legends:

• Marco Pessotto <melmothx@gmail.com>
• Oleg A. Mamontov <oleg@mamontov.net>
• Rusty Conover <https://github.com/rustyconover>
• Stefan Hornburg <racke@linuxia.de>

---

👀 SEE ALSO

go read these too, bestie, they're the supporting cast:

• Email::Sender
• MIME::Entity

---

👑 AUTHORS

• Naveed Massjouni <naveed@vt.edu>
• Al Newkirk <awncorp@cpan.org>

---

📜 COPYRIGHT AND LICENSE

this software is copyright (c) 2010 by awncorp. 🫶

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay.

---

and that's the whole page, bestie 💅 this was Dancer::Plugin::Email, documented in the User Contributed Perl Documentation, running on perl v5.34.0, dated 2022-06-12. mwah. 🎀✨💖