NAME
Dancer::Plugin::EmailSender - Easily use Email::Sender from Dancer
VERSION
version 0.002
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.