-
-
27 Oct 2020 11:27:28 UTC
- Distribution: Mojolicious-Plugin-EmailMailer
- Module version: 0.02
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues
- Testers (144 / 11 / 15)
- Kwalitee
Bus factor: 1- 76.42% Coverage
- License: perl_5
- Perl: v5.20.0
- Activity
24 month- Tools
- Download (8.93KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Email::Mailer
- Email::Sender
- Hash::Merge
- MIME::Words
- Mojolicious
- Try::Tiny
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- CONFIGURATION
- HELPERS
- EXAMPLES
- METHODS
- BUGS and SUPPORT
- AUTHOR
- COPYRIGHT
- SEE ALSO
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
andhowargs
, the configuration parameters are parameters for Email::Mailer’snew
method. See https://metacpan.org/pod/Email::Mailer#PARAMETERS for available parameters. Those parameters will be the default ones and can be overwritten when usingsend_mail
andsend_multiple_mail
helpers (see below).As for
how
andhowargs
parameters, they are used to choose the transport for the mails (sendmail
, a SMTP server…). Thehow
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 ofEmail::Sender::Transport::$how
, constructed withhowargs
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
andrender_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
andFrom
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
andContent-Type
headers are respectivelyquoted-printable
andtext/plain; charset=utf8
and the text is encoded according to the charset specified in theContent-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 theEmail::Mailer-
new()> arguments andsend
, an arrayref, contains theEmail::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
andContent-Type
headers are respectivelyquoted-printable
andtext/plain; charset=utf8
and the text is encoded according to the charset specified in theContent-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.git
Bugs and feature requests will be tracked at:
https://framagit.org/fiat-tux/mojolicious/mojolicious-plugin-emailmailer/issues
AUTHOR
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.
Module Install Instructions
To install Mojolicious::Plugin::EmailMailer, copy and paste the appropriate command in to your terminal.
cpanm Mojolicious::Plugin::EmailMailer
perl -MCPAN -e shell install Mojolicious::Plugin::EmailMailer
For more information on module installation, please visit the detailed CPAN module installation guide.