=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 => '[email protected]',
   type => 'text/html',
 });

 # in controller
 $self->mail(
   to      => '[email protected]',
   subject => 'Test',
   data    => 'use Perl or die;',
 );

 # in controller, using render
 $self->mail(to => '[email protected]', 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       => '[email protected]',
     from     => '[email protected]',

     reply_to => '[email protected]',

     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      => '[email protected]',
       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<[email protected]>.

=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     => '[email protected],
   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      => '[email protected]',
     type    => 'text/plain',
     subject => 'Тест письмо',
     data    => 'Привет!',
   );
 };

Simple send mail:

 get '/simple' => sub {
   my $self = shift;

   $self->mail(
     mail => {
       To      => '[email protected]',
       Subject => 'Тест письмо',
       Data    => "<p>Привет!</p>",
     },
   );
 };

Simple send mail with test mode:

 get '/simple2' => sub {
   my $self = shift;

   my $mail = $self->mail(
     test => 1,
     mail => {
       To      => '"Анатолий Шарифулин" [email protected]',
       Cc      => '"Анатолий Шарифулин" <[email protected]>, Anatoly Sharifulin [email protected]',
       Bcc     => '[email protected]',
       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      => '[email protected]',
       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      => '[email protected]',
       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 => '[email protected]', reply_to => '[email protected]');

   $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      => '[email protected]',
       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 <[email protected]>

=head1 THANKS

Alex Kapranoff <[email protected]>

=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-2013 by Anatoly Sharifulin.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

=cut

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.