NAME
Mojolicious::Plugin::EmailMailer - Mojolicious Plugin to send mail through Email::Mailer.
SYNOPSIS
# Mojolicious
$self->plugin('EmailMailer');
# Mojolicious with config
$self->plugin('EmailMailer' => {
from => 'example@example.org',
how => 'smtp',
howargs => {
hosts => [ 'smtp.example.org' ],
ssl => 1, # can be 'starttls'
sasl_username => 'user_login',
sasl_password => 's3cr3t'
}
});
# Mojolicious::Lite
plugin 'EmailMailer';
# Mojolicious::Lite with config
plugin 'EmailMailer' => {
from => 'example@example.org',
how => 'smtp',
howargs => {
hosts => [ 'smtp.example.org' ],
ssl => 1, # can be 'starttls'
sasl_username => 'user_login',
sasl_password => 's3cr3t'
}
}DESCRIPTION
Mojolicious::Plugin::EmailMailer is a Mojolicious plugin to send mail through Email::Mailer.
Inspired by Mojolicious::Plugin::Mail, I needed to be able to send mail through a server which uses starttls.
CONFIGURATION
All parameters are optional.
Except for how and howargs, the configuration parameters are parameters for Email::Mailer’s new method. See https://metacpan.org/pod/Email::Mailer#PARAMETERS for available parameters. Those parameters will be the default ones and can be overwritten when using send_mail and send_multiple_mail helpers (see below).
As for how and howargs parameters, they are used to choose the transport for the mails (sendmail, a SMTP server…). The how parameter can be:
- DevNull - happily throw away your mail
- Failable - a wrapper to makes things fail predictably
- Maildir - deliver mail to a maildir on disk
- Mbox - deliver mail to an mbox on disk
- Print - print email to a filehandle (like stdout)
- SMTP - send email over SMTP
- SMTP::Persistent - an SMTP client that stays online
- Sendmail - send mail via sendmail(1)
- Test - deliver mail in memory for testing
- Wrapper - a mailer to wrap a mailer for mailing mail
Note that the how parameter is case-insensitive.
When giving a how parameter, the transport will be an instance of Email::Sender::Transport::$how, constructed with howargs as parameters.
See https://metacpan.org/release/Email-Sender to find the available parameters for the transport you want to use.
HELPERS
Mojolicious::Plugin::EmailMailer contains three helpers: send_mail, send_multiple_mail and render_mail.
send_mail
Straightly send a mail, according to the given arguments and plugin configuration.
$self->send_mail(
to => 'test@example.org',
from => 'test@example.org',
'reply-to' => 'reply_to+test@example.org',
cc => '..',
bcc => '..',
subject => 'Test',
text => 'use Perl or die;',
html => '</p>use Perl or die;</p>',
);See https://metacpan.org/pod/Email::Mailer#PARAMETERS for available parameters.
If send_mail() succeeds, it'll return an instantiated Email::Mailer object based on the combined parameters. If it fails, it will return 0 and create a log error message;
All parameters, will be used as mail headers, except the following ones:
- html
- text
- embed
- attachments
- process
- data
- transport
- width
Note that the Subject, to and From headers will be automatically UTF-8 encoded by the plugin, then encoded as mimewords by Email::Mailer.
When sending a text-only mail (with or without attachments), the default values of Content-Transfer-Encoding and Content-Type headers are respectively quoted-printable and text/plain; charset=utf8 and the text is encoded according to the charset specified in the Content-Type header;
send_multiple_mail
Email::Mailer allows to prepare a mail and send it more than one time, with different overriden parameters:
Email::Mailer->new(
from => $from,
subject => $subject,
html => $html
)->send(
{ to => 'person_0@example.com' },
{ to => 'person_1@example.com' },
{
to => 'person_2@example.com',
subject => 'Override $subject with this',
}
);You can do the same with send_multiple_mail:
$self->send_multiple_mail(
mail => {
from => $from,
subject => $subject,
html => $html
},
send => [
{ to => 'person_0@example.com' },
{ to => 'person_1@example.com' },
{
to => 'person_2@example.com',
subject => 'Override $subject with this',
}
]
);mail, a hashref, obviously contains the Email::Mailer-new()> arguments and send, an arrayref, contains the Email::Mailer-send()> arguments.
If send_multiple_mail() succeeds, it'll return an array or arrayref (based on context) of the Email::Mailer objects ultimately created. If it fails, it will return 0 and create a log error message;
Note that the subject will be UTF-8 encoded, then encoded as mimeword, like this:
use MIME::Words qw(encode_mimeword);
$subject = encode_mimeword(encode('UTF-8', $subject), 'q', 'UTF-8');When sending a text-only mail (with or without attachments), the default values of Content-Transfer-Encoding and Content-Type headers are respectively quoted-printable and text/plain; charset=utf8 and the text is encoded according to the charset specified in the Content-Type header;
render_mail
my $data = $self->render_mail('user/signup');
# or use stash params
my $data = $self->render_mail(template => 'user/signup', user => $user);Render mail template and return data, mail template format is mail, i.e. user/signup.mail.ep.
EXAMPLES
my ($to, $from, $subject, $text, $html);
# send a simple text email
$self->send_mail(
to => $to,
from => $from,
subject => $subject,
text => $text
);
# send multi-part HTML/text email with the text auto-generated from the HTML
# and images and other resources embedded in the email
$self->send_mail(
to => $to,
from => $from,
subject => $subject,
html => $html
);
# send multi-part HTML/text email with the text auto-generated from the HTML
# but skip embedding images and other resources
$self->send_mail(
to => $to,
from => $from,
subject => $subject,
html => $html,
embed => 0
);
# send multi-part HTML/text email but supply the text explicitly
$self->send_mail(
to => $to,
from => $from,
subject => $subject,
html => $html,
text => $text
);
# send multi-part HTML/text email with a couple of attached files
use IO::All 'io';
$self->send_mail(
to => $to,
from => $from,
subject => $subject,
html => $html,
text => $text,
attachments => [
{
ctype => 'application/pdf',
source => 'file.pdf',
},
{
ctype => 'application/pdf',
content => io('file.pdf')->binary->all,
encoding => 'base64',
name => 'file.pdf',
},
],
);
# build an email and iterate over a data set for sending
$self->send_multiple_mail(
mail => {
from => $from,
subject => $subject,
html => $html
},
send => [
{ to => 'person_0@example.com' },
{ to => 'person_1@example.com' },
{
to => 'person_2@example.com',
subject => 'Override $subject with this',
}
]
);
# setup a second mail object based on the first but changing the "from"
my $mail_0 = $self->send_mail(
from => $from,
subject => $subject,
html => $html
);
if ($mail_0) {
my $mail_1 = $mail_0->new(from => 'different_address@example.com');
$mail_1->send;
}METHODS
Mojolicious::Plugin::EmailMailer inherits all methods from Mojolicious::Plugin and implements the following new ones.
register
$plugin->register(Mojolicious->new);Register plugin in Mojolicious application.
BUGS and SUPPORT
The latest source code can be browsed and fetched at:
https://framagit.org/fiat-tux/mojolicious/mojolicious-plugin-emailmailer
git clone https://framagit.org/fiat-tux/mojolicious/mojolicious-plugin-emailmailer.gitBugs and feature requests will be tracked at:
https://framagit.org/fiat-tux/mojolicious/mojolicious-plugin-emailmailer/issuesAUTHOR
Luc DIDRY
CPAN ID: LDIDRY
ldidry@cpan.org
https://fiat-tux.fr/COPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
Mojolicious, Mojolicious::Guides, Email::Mailer, Email::Sender, https://mojolicious.org.