=encoding UTF-8
=head1 NAME
Mojolicious::Plugin::Mail - Mojolicious Plugin for send mail
=head1 SYNOPSIS
# Mojolicious::Lite
plugin 'mail';
# Mojolicious with config
$self->plugin(mail => {
from => 'sharifulin@gmail.com',
type => 'text/html',
});
# in controller
$self->mail(
to => 'sharifulin@gmail.com',
subject => 'Test',
data => 'use Perl or die;',
);
# in controller, using render
$self->mail(to => 'sharifulin@gmail.com', template => 'controller/action', format => 'mail');
# template: controller/action.mail.ep
% stash subject => 'Test';
use Perl or die;
=head1 DESCRIPTION
L<Mojolicous::Plugin::Mail> is a plugin for Mojolicious apps to send mail using L<MIME::Lite>.
Mojolicious 4.0 ready.
=head1 HELPERS
L<Mojolicious::Plugin::Mail> contains two helpers: I<mail> and I<render_mail>.
=head2 C<mail>
# simple interface
$self->mail(
to => 'sharifulin@gmail.com',
from => 'sharifulin@gmail.com',
reply_to => 'reply_to+sharifulin@gmail.com',
cc => '..',
bcc => '..',
type => 'text/plain',
subject => 'Test',
data => 'use Perl or die;',
);
# interface as MIME::Lite
$self->mail(
# test mode
test => 1,
# as MIME::Lite->new( ... )
mail => {
To => 'sharifulin@gmail.com',
Subject => 'Test',
Data => 'use Perl or die;',
},
attach => [
# as MIME::Lite->attach( .. )
{ ... },
...
},
headers => [
# as MIME::Lite->add( .. )
{ ... },
...
},
attr => [
# as MIME::Lite->attr( .. )
{ ... },
...
},
);
Build and send email, return mail as string.
Supported parameters:
=over 16
=item * to
Header 'To' of mail.
=item * from
Header 'From' of mail.
=item * reply_to
Header 'Reply-To' of mail.
=item * cc
Header 'Cc' of mail.
=item * bcc
Header 'Bcc' of mail.
=item * type
Content type of mail, default is conf's type.
=item * subject
Header 'Subject' of mail.
=item * data
Content of mail
=item * mail
Hashref, containts parameters as I<new(PARAMHASH)>. See L<MIME::Lite>.
=item * attach
Arrayref of hashref, hashref containts parameters as I<attach(PARAMHASH)>. See L<MIME::Lite>.
=item * headers
Arrayref of hashref, hashref containts parameters as I<add(TAG, VALUE)>. See L<MIME::Lite>.
=item * attr
Arrayref of hashref, hashref containts parameters as I<attr(ATTR, VALUE)>. See L<MIME::Lite>.
=item * test
Test mode, don't send mail.
=item * charset
Charset of mail, default charset is UTF-8.
=item * mimeword
Using mimeword or not, default value is 1.
=item * nomailer
No using 'X-Mailer' header of mail, default value is 1.
=back
If no subject, uses value of stash parameter 'subject'.
If no data, call I<render_mail> helper with all stash parameters.
=head2 C<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 I<mail>, i.e. I<user/signup.mail.ep>.
=head1 ATTRIBUTES
L<Mojolicious::Plugin::Mail> contains one attribute - conf.
=head2 C<conf>
$plugin->conf;
Config of mail plugin, hashref.
Keys of conf:
=over 6
=item * from
From address, default value is I<test-mail-plugin@mojolicio.us>.
=item * encoding
Encoding of Subject and any Data, value is MIME::Lite content transfer encoding L<http://search.cpan.org/~rjbs/MIME-Lite-3.027/lib/MIME/Lite.pm#Content_transfer_encodings>
Default value is I<base64>.
=item * charset
Default charset of Subject and any Data, default value is I<UTF-8>.
=item * type
Default type of Data, default value is I<text/plain>.
=item * how
HOW parameter of MIME::Lite::send: I<sendmail> or I<smtp>.
=item * howargs
HOWARGS parameter of MIME::Lite::send (arrayref).
=back
my $conf = {
from => 'sharifulin@gmail.com,
encoding => 'base64',
type => 'text/html',
how => 'sendmail',
howargs => [ '/usr/sbin/sendmail -t' ],
};
# in Mojolicious app
$self->plugin(mail => $conf);
# in Mojolicious::Lite app
plugin mail => $conf;
=head1 METHODS
L<Mojolicious::Plugin::Mail> inherits all methods from
L<Mojolicious::Plugin> and implements the following new ones.
=head2 C<register>
$plugin->register($app, $conf);
Register plugin hooks in L<Mojolicious> application.
=head2 C<build>
$plugin->build( mail => { ... }, ... );
Build mail using L<MIME::Lite> and L<MIME::EncWords> and return MIME::Lite object.
=head1 TEST MODE
L<Mojolicious::Plugin::Mail> has test mode, no send mail.
# all mail don't send mail
BEGIN { $ENV{MOJO_MAIL_TEST} = 1 };
# or only once
$self->mail(
test => 1,
to => '...',
);
=head1 EXAMPLES
The Mojolicious::Lite example you can see in I<example/test.pl>.
Simple interface for send plain mail:
get '/simple' => sub {
my $self = shift;
$self->mail(
to => 'sharifulin@gmail.com',
type => 'text/plain',
subject => 'Тест письмо',
data => 'Привет!',
);
};
Simple send mail:
get '/simple' => sub {
my $self = shift;
$self->mail(
mail => {
To => 'sharifulin@gmail.com',
Subject => 'Тест письмо',
Data => "<p>Привет!</p>",
},
);
};
Simple send mail with test mode:
get '/simple2' => sub {
my $self = shift;
my $mail = $self->mail(
test => 1,
mail => {
To => '"Анатолий Шарифулин" sharifulin@gmail.com',
Cc => '"Анатолий Шарифулин" <sharifulin@gmail.com>, Anatoly Sharifulin sharifulin@gmail.com',
Bcc => 'sharifulin@gmail.com',
Subject => 'Тест письмо',
Type => 'text/plain',
Data => "<p>Привет!</p>",
},
);
warn $mail;
};
Mail with binary attachcment, charset is windows-1251, mimewords off and mail has custom header:
get '/attach' => sub {
my $self = shift;
my $mail = $self->mail(
charset => 'windows-1251',
mimeword => 0,
mail => {
To => 'sharifulin@gmail.com',
Subject => 'Test attach',
Type => 'multipart/mixed'
},
attach => [
{
Data => 'Any data',
},
{
Type => 'BINARY',
Filename => 'crash.data',
Disposition => 'attachment',
Data => 'binary data binary data binary data binary data binary data',
},
],
headers => [ { 'X-My-Header' => 'Mojolicious' } ],
);
};
Multipart mixed mail:
get '/multi' => sub {
my $self = shift;
$self->mail(
mail => {
To => 'sharifulin@gmail.com',
Subject => 'Мульти',
Type => 'multipart/mixed'
},
attach => [
{
Type => 'TEXT',
Encoding => '7bit',
Data => "Just a quick note to say hi!"
},
{
Type => 'image/gif',
Path => $0
},
{
Type => 'x-gzip',
Path => "gzip < $0 |",
ReadNow => 1,
Filename => "somefile.zip"
},
],
);
};
Render mail using simple interface and Reply-To header:
get '/render_simple' => sub {
my $self = shift;
my $mail = $self->mail(to => 'sharifulin@gmail.com', reply_to => 'reply_to+sharifulin@gmail.com');
$self->render(ok => 1, mail => $mail);
} => 'render';
Mail with render data and subject from stash param:
get '/render' => sub {
my $self = shift;
my $data = $self->render_mail('render');
$self->mail(
mail => {
To => 'sharifulin@gmail.com',
Subject => $self->stash('subject'),
Data => $data,
},
);
} => 'render';
__DATA__
@@ render.html.ep
<p>Hello render!</p>
@@ render.mail.ep
% stash 'subject' => 'Привет render';
<p>Привет mail render!</p>
=head1 SEE ALSO
L<MIME::Lite> L<MIME::EncWords> L<Mojolicious> L<Mojolicious::Guides> L<http://mojolicious.org>.
=head1 AUTHOR
Anatoly Sharifulin <sharifulin@gmail.com>
=head1 THANKS
Alex Kapranoff <kapranoff@gmail.com>
=head1 BUGS
Please report any bugs or feature requests to C<bug-mojolicious-plugin-mail at rt.cpan.org>, or through
the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.htMail?Queue=Mojolicious-Plugin-Mail>. We will be notified, and then you'll
automatically be notified of progress on your bug as we make changes.
=over 5
=item * Github
L<http://github.com/sharifulin/mojolicious-plugin-mail/tree/master>
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.htMail?Dist=Mojolicious-Plugin-Mail>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/Mojolicious-Plugin-Mail>
=item * CPANTS: CPAN Testing Service
L<http://cpants.perl.org/dist/overview/Mojolicious-Plugin-Mail>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/Mojolicious-Plugin-Mail>
=item * Search CPAN
L<http://search.cpan.org/dist/Mojolicious-Plugin-Mail>
=back
=head1 COPYRIGHT & LICENSE
Copyright (C) 2010-2015 by Anatoly Sharifulin.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut