The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Mojolicious-Plugin-EmailMailer-0.03
River stage zero No dependents
/ Mojolicious::Plugin::EmailMailer

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
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.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.