lib/Catalyst/Plugin/Email.pm

   1 package Catalyst::Plugin::Email;
   2
   3 use strict;
   4 use Email::Send;
   5 use Email::MIME;
   6 use Email::MIME::Creator;
   7
   8 our $VERSION = '0.09';
   9
  10 =head1 NAME
  11
  12 Catalyst::Plugin::Email - (DEPRECATED) Send emails with Catalyst
  13
  14 =head1 SYNOPSIS
  15
  16     # please use Email::MIME::Kit or Catalyst::View::Email::Template instead
  17
  18     use Catalyst 'Email';
  19
  20     __PACKAGE__->config->{email} = [qw/SMTP smtp.oook.de/];
  21
  22     $c->email(
  23         header => [
  24             From    => 'sri@oook.de',
  25             To      => 'sri@cpan.org',
  26             Subject => 'Hello!'
  27         ],
  28         body => 'Hello sri'
  29     );
  30
  31 =head1 DESCRIPTION
  32
  33 Send emails with Catalyst and L<Email::Send> and L<Email::MIME::Creator>.
  34
  35 =head1 CONFIGURATION
  36
  37 C<config> accepts the same options as L<Email::Send>.
  38
  39 To send using the system's C<sendmail> program, set C<config> like so:
  40
  41     __PACKAGE__->config->{email} = ['Sendmail'];
  42
  43 To send using authenticated SMTP:
  44
  45     __PACKAGE__->config->{email} = [
  46         'SMTP',
  47         'smtp.myhost.com',
  48         username => $USERNAME,
  49         password => $PASSWORD,
  50     ];
  51
  52 For different methods of sending emails, and appropriate C<config> options,
  53 see L<Email::Send::NNTP>, L<Email::Send::Qmail>, L<Email::Send::SMTP> and
  54 L<Email::Send::Sendmail>.
  55
  56 =head1 METHODS
  57
  58 =head2 email
  59
  60 C<email()> accepts the same arguments as L<Email::MIME::Creator>'s
  61 C<create()>.
  62
  63     $c->email(
  64         header => [
  65             To      => 'me@localhost',
  66             Subject => 'A TT Email',
  67         ],
  68         body => $c->subreq( '/render_email' ),
  69     );
  70
  71 To send a multipart message, include a C<parts> argument containing an
  72 arrayref of Email::MIME objects.
  73
  74     my @parts = (
  75         Email::MIME->create(
  76             attributes => {
  77                 content_type => 'application/pdf',
  78                 encoding     => 'quoted-printable',
  79                 name         => 'report.pdf',
  80             },
  81             body => $FILE_DATA,
  82         ),
  83         Email::MIME->create(
  84             attributes => {
  85                 content_type => 'text/plain',
  86                 disposition  => 'attachment',
  87                 charset      => 'US-ASCII',
  88             },
  89             body => $c->subreq( '/render_email' ),
  90         ),
  91     );
  92
  93     $c->email(
  94         header => [
  95             To      => 'me@localhost',
  96             Subject => 'A TT Email',
  97         ],
  98         parts => \@parts,
  99     );
 100
 101 =cut
 102
 103 sub email {
 104     my $c = shift;
 105     my $email = $_[1] ? {@_} : $_[0];
 106     $email = Email::MIME->create(%$email);
 107     my $args = $c->config->{email} || [];
 108     my @args = @{$args};
 109     my $class;
 110     unless ( $class = shift @args ) {
 111         $class = 'SMTP';
 112         unshift @args, 'localhost';
 113     }
 114     send $class => $email, @args;
 115 }
 116
 117 =head1 USING WITH A VIEW
 118
 119 A common practice is to handle emails using the same template language used
 120 for HTML pages.  If your view supports the 'render' method (Like the TT view
 121 does), you just set the body like this:
 122   $c->email(
 123      header => [
 124         To      => 'me@localhost',
 125         Subject => 'A TT Email',
 126      ],
 127      body => $c->view('TT')->render($c,'mytemplate.tt'),
 128   }
 129
 130 If your view doesn't support render, you can just forward to it, then reset
 131 the body like this:
 132
 133     sub send_email : Local {
 134         my ( $self, $c ) = @_;
 135         {
 136         local $c->stash->{names}   = [ qw/andyg sri mst/ ],
 137         local $c->stash->{template}= 'mytemplate.tt';
 138         $c->forward($c->view('MyView'));
 139         $c->email(
 140             header => [
 141                 To      => 'me@localhost',
 142                 Subject => 'A TT Email',
 143             ],
 144             body => $c->res->body,
 145         );
 146         $c->res->body(undef);
 147         }
 148     }
 149
 150 And the template:
 151
 152     [%- FOREACH name IN names -%]
 153     Hi, [% name %]!
 154     [%- END -%]
 155
 156     --
 157     Regards,
 158     Us
 159
 160 Output:
 161
 162     Hi, andyg!
 163     Hi, sri!
 164     Hi, mst!
 165
 166     --
 167     Regards,
 168     Us
 169
 170 =head1 SEE ALSO
 171
 172 L<Catalyst>, L<Catalyst::Plugin::SubRequest>, L<Email::Send>,
 173 L<Email::MIME::Creator>
 174
 175 =head1 AUTHOR
 176
 177 Sebastian Riedel, C<sri@cpan.org>
 178 Andy Grundman
 179 Carl Franks
 180 Marcus Ramberg C<mramberg@cpan.org>
 181
 182 =head1 COPYRIGHT
 183
 184 This program is free software, you can redistribute it and/or modify it
 185 under the same terms as Perl itself.
 186
 187 =cut
 188
 189 1;