NAME

Dancer::Plugin::EmailSender - Easily use Email::Sender from Dancer

VERSION

version 0.001

SYNOPSIS

    use Dancer;
    use Dancer::Plugin::EmailSender;

    post '/signup' => sub {
        sendemail {
            body            => '...',
            'envelope-from' => 'signup-@ironicdesign.com-@[]' # Allows VERP-handling with postfix
            from            => 'mdorman@ironicdesign.com',
            subject         => 'Welcome to our site',
            to              => param ('email')
        };
    };

DESCRIPTION

This plugin makes constructing and sending emails from Dancer applications as simple and flexible as possible. Since it uses Email::Sender, in many cases, no explicit configuration may be required, though several configuration options are available.

CONFIGURATION

You can configure a number of defaults for the plugin in the your config.yml or appropriate environment config file. Anything that you configure in this way can be overridden at the time sendemail is called.

Transport

Dancer::Plugin::EmailSender allows you to choose and configure a particular transport, should you not wish to use the one that Email::Sender would choose by default (as discussed in the Email::Sender manual).

Simply add a transport key, pointing to a set of options that must include a class entry (stating the name of the subclass of Email::Sender::Transport:* to be used for the transport), while any additional entries will be used as parameters for instantiating the transport:

For example, to send mail using SMTPS via Gmail:

    plugins:
      EmailSender:
        transport:
          class: SMTP:
          ssl: 1
          host: 'smtp.gmail.com'
          port: 465
          sasl_username: 'mdorman@ironicdesign.com'
          sasl_password: 'NotMuchOfASecret'

Or perhaps to use the default Sendmail transport, but give an explicit path to the sendmail program:

    plugins:
      EmailSender:
        transport:
          class: Sendmail
          sendmail: '/usr/sbin/sendmail'

Headers

You may also provide a set of default headers in the configuration:

    plugins:
      EmailSender:
        headers:
          From: 'noreply@ironicdesign.com'
          X-Mailer: 'Degronkulator 3.14'
          X-Accept-Language: 'en'

sendemail

This function will optionally construct, and then send, an email. It takes a hashref of parameters. They can be divided up as to their purpose:

Specifying the content to send

To specify the content of the email to send, you may either:

Provide a complete email to be sent

If a completed email (in a format that is acceptable to Email::Abstract is provided in an email parameter, that is the email that will be sent.

Provide parameters to construct an email

These parameters include:

from

The address from which the email should be sent.

to

An arrayref od address to which the email should be sent.

headers

A hashref of additional headers to add to the email.

body

The body of the actual email to be sent.

Specifying how the email is sent

You may optionally specify the transport here, overriding any defaults or settings in your application configuration. All configuration will appear under a transport key.

From there you can specify the transport to use two different ways.

Provide a set of construction parameters

The parameters you hand in will be used just as if they had appeared in the configuration to create a new transport, which will then be used for this transaction.

Provide a constructed Transport

You may construct your own transport and simply hand that in to the sendemail routine.

Specifying the sending and retrieving addresses

You may independently set the sending and receiving addresses for the SMTP transaction, allowing them to be different from the values in the headers of your email. To do this you can include either or both of:

envelope-from

This is the address that will be used as the sending address during the SMTP transaction.

envelope-to

This is the list of addresse that will be used as recipients during the SMTP transaction.

Error Handling

An exception will be thrown if sending the email fails, so plan appropriately.

AUTHOR

Michael Alan Dorman <mdorman@ironicdesign.com>

Although I started out just wanting to fix things in Dancer::Plugin::Email, I ended up rewriting everything. Still, Naveed Massjouni <naveedm9@gmail.com> and Al Newkirk <awncorp@cpan.org> deserve credit for writing Dancer::Plugin::Email.

AUTHOR

Michael Alan Dorman <mdorman@ironicdesign.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Michael Alan Dorman.

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

cpanm Dancer::Plugin::EmailSender

perl -MCPAN -e shell
install Dancer::Plugin::EmailSender