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