<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;"># NAME

Mojolicious::Plugin::EmailMailer - Mojolicious Plugin to send mail through Email::Mailer.

# SYNOPSIS

    # Mojolicious
    $self-&gt;plugin('EmailMailer');

    # Mojolicious with config
    $self-&gt;plugin('EmailMailer' =&gt; {
      from =&gt; 'example@example.org',
      how  =&gt; 'smtp',
      howargs =&gt; {
          hosts =&gt; [ 'smtp.example.org' ],
          ssl   =&gt; 1, # can be 'starttls'
          sasl_username =&gt; 'user_login',
          sasl_password =&gt; 's3cr3t'
      }
    });

    # Mojolicious::Lite
    plugin 'EmailMailer';

    # Mojolicious::Lite with config
    plugin 'EmailMailer' =&gt; {
      from =&gt; 'example@example.org',
      how  =&gt; 'smtp',
      howargs =&gt; {
          hosts =&gt; [ 'smtp.example.org' ],
          ssl   =&gt; 1, # can be 'starttls'
          sasl_username =&gt; 'user_login',
          sasl_password =&gt; 's3cr3t'
      }
    }

# DESCRIPTION

[Mojolicious::Plugin::EmailMailer](https://metacpan.org/pod/Mojolicious::Plugin::EmailMailer) is a [Mojolicious](https://metacpan.org/pod/Mojolicious) plugin to send mail through Email::Mailer.

Inspired by [Mojolicious::Plugin::Mail](https://metacpan.org/pod/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](https://metacpan.org/pod/Email::Mailer)窶冱 `new` method.
See [https://metacpan.org/pod/Email::Mailer#PARAMETERS](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](https://metacpan.org/release/Email-Sender) to find the available parameters for the transport you want to use.

# HELPERS

[Mojolicious::Plugin::EmailMailer](https://metacpan.org/pod/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-&gt;send_mail(
        to         =&gt; 'test@example.org',
        from       =&gt; 'test@example.org',
        'reply-to' =&gt; 'reply_to+test@example.org',
        cc         =&gt; '..',
        bcc        =&gt; '..',
        subject    =&gt; 'Test',
        text       =&gt; 'use Perl or die;',
        html       =&gt; '&lt;/p&gt;use Perl or die;&lt;/p&gt;',
    );

See [https://metacpan.org/pod/Email::Mailer#PARAMETERS](https://metacpan.org/pod/Email::Mailer#PARAMETERS) for available parameters.

If `send_mail()` succeeds, it'll return an instantiated [Email::Mailer](https://metacpan.org/pod/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](https://metacpan.org/pod/Email::Mailer#AUTOMATIC-HEADER-IFICATION).

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](https://metacpan.org/pod/Email::Mailer) allows to prepare a mail and send it more than one time, with different overriden parameters:

    Email::Mailer-&gt;new(
        from    =&gt; $from,
        subject =&gt; $subject,
        html    =&gt; $html
    )-&gt;send(
        { to =&gt; 'person_0@example.com' },
        { to =&gt; 'person_1@example.com' },
        {
            to      =&gt; 'person_2@example.com',
            subject =&gt; 'Override $subject with this',
        }
    );

You can do the same with `send_multiple_mail`:

    $self-&gt;send_multiple_mail(
        mail =&gt; {
            from    =&gt; $from,
            subject =&gt; $subject,
            html    =&gt; $html
        },
        send =&gt; [
            { to =&gt; 'person_0@example.com' },
            { to =&gt; 'person_1@example.com' },
            {
                to      =&gt; 'person_2@example.com',
                subject =&gt; 'Override $subject with this',
            }
        ]
    );

`mail`, a hashref, obviously contains the `Email::Mailer-`new()&gt; arguments and `send`, an arrayref,
contains the `Email::Mailer-`send()&gt; arguments.

If `send_multiple_mail()` succeeds, it'll return an array or arrayref (based on context) of the [Email::Mailer](https://metacpan.org/pod/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-&gt;render_mail('user/signup');

    # or use stash params
    my $data = $self-&gt;render_mail(template =&gt; 'user/signup', user =&gt; $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-&gt;send_mail(
        to      =&gt; $to,
        from    =&gt; $from,
        subject =&gt; $subject,
        text    =&gt; $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-&gt;send_mail(
        to      =&gt; $to,
        from    =&gt; $from,
        subject =&gt; $subject,
        html    =&gt; $html
    );

    # send multi-part HTML/text email with the text auto-generated from the HTML
    # but skip embedding images and other resources
    $self-&gt;send_mail(
        to      =&gt; $to,
        from    =&gt; $from,
        subject =&gt; $subject,
        html    =&gt; $html,
        embed   =&gt; 0
    );

    # send multi-part HTML/text email but supply the text explicitly
    $self-&gt;send_mail(
        to      =&gt; $to,
        from    =&gt; $from,
        subject =&gt; $subject,
        html    =&gt; $html,
        text    =&gt; $text
    );

    # send multi-part HTML/text email with a couple of attached files
    use IO::All 'io';
    $self-&gt;send_mail(
        to          =&gt; $to,
        from        =&gt; $from,
        subject     =&gt; $subject,
        html        =&gt; $html,
        text        =&gt; $text,
        attachments =&gt; [
            {
                ctype  =&gt; 'application/pdf',
                source =&gt; 'file.pdf',
            },
            {
                ctype    =&gt; 'application/pdf',
                content  =&gt; io('file.pdf')-&gt;binary-&gt;all,
                encoding =&gt; 'base64',
                name     =&gt; 'file.pdf',
            },
        ],
    );

    # build an email and iterate over a data set for sending
    $self-&gt;send_multiple_mail(
        mail =&gt; {
            from    =&gt; $from,
            subject =&gt; $subject,
            html    =&gt; $html
        },
        send =&gt; [
            { to =&gt; 'person_0@example.com' },
            { to =&gt; 'person_1@example.com' },
            {
                to      =&gt; 'person_2@example.com',
                subject =&gt; 'Override $subject with this',
            }
        ]
    );

    # setup a second mail object based on the first but changing the "from"
    my $mail_0 = $self-&gt;send_mail(
        from    =&gt; $from,
        subject =&gt; $subject,
        html    =&gt; $html
    );
    if ($mail_0) {
        my $mail_1 = $mail_0-&gt;new(from =&gt; 'different_address@example.com');
        $mail_1-&gt;send;
    }

# METHODS

[Mojolicious::Plugin::EmailMailer](https://metacpan.org/pod/Mojolicious::Plugin::EmailMailer) inherits all methods from
[Mojolicious::Plugin](https://metacpan.org/pod/Mojolicious::Plugin) and implements the following new ones.

## register

    $plugin-&gt;register(Mojolicious-&gt;new);

Register plugin in [Mojolicious](https://metacpan.org/pod/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](https://metacpan.org/pod/Mojolicious), [Mojolicious::Guides](https://metacpan.org/pod/Mojolicious::Guides), [Email::Mailer](https://metacpan.org/pod/Email::Mailer), [Email::Sender](https://metacpan.org/pod/Email::Sender), [https://mojolicious.org](https://mojolicious.org).
</pre></body></html>