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.06';
  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->view('TT')->render($c, 'email.tt', {
  68            additional_template_paths => [ $c->config->{root} . '/email_templates'],
  69            }
  70         ),
  71     );
  72
  73 To send a multipart message, include a C<parts> argument containing an
  74 arrayref of Email::MIME objects.
  75
  76     my @parts = (
  77         Email::MIME->create(
  78             attributes => {
  79                 content_type => 'application/pdf',
  80                 encoding     => 'quoted-printable',
  81                 name         => 'report.pdf',
  82             },
  83             body => $FILE_DATA,
  84         ),
  85         Email::MIME->create(
  86             attributes => {
  87                 content_type => 'text/plain',
  88                 disposition  => 'attachment',
  89                 charset      => 'US-ASCII',
  90             },
  91             body => $c->view('TT')->render($c, 'email.tt', {
  92                additional_template_paths => [ $c->config->{root} . '/email_templates'],
  93                names => [qw/foo bar baz/]
  94                }
  95             ),
  96         ),
  97     );
  98
  99     $c->email(
 100         header => [
 101             To      => 'me@localhost',
 102             Subject => 'A TT Email',
 103         ],
 104         parts => \@parts,
 105     );
 106
 107 =cut
 108
 109 sub email {
 110     my $c = shift;
 111     my $email = $_[1] ? {@_} : $_[0];
 112     croak "Can't send mail without recipient"
 113         unless length($email->{To});
 114     $email = Email::MIME->create(%$email);
 115     my $args = $c->config->{email} || [];
 116     my @args = @{$args};
 117     my $class;
 118     unless ( $class = shift @args ) {
 119         $class = 'SMTP';
 120         unshift @args, 'localhost';
 121     }
 122     send $class => $email, @args;
 123 }
 124
 125 =head1 USING WITH A VIEW
 126
 127 A common practice is to handle emails using the same template language used
 128 for HTML pages.  This is best accomplished by capturing the output from the
 129 template. For TT this is done using the C<render> method as described in
 130 L<Catalyst::View:TT/CAPTURING TEMPLATE OUTPUT>.
 131
 132 Here is a short example of rendering an email from a Template Toolkit source
 133 file.  For more information on render (or how to do this with a view other
 134 than TT, consult the docs for your view)
 135
 136     sub send_email : Local {
 137         my ( $self, $c ) = @_;
 138
 139         $c->email(
 140             header => [
 141                 To      => 'me@localhost',
 142                 Subject => 'A TT Email',
 143             ],
 144             body => $c->view('TT')->render('email.tt',
 145              {  additional_template_paths => [ $c->config->{root} . '/email_templates'],
 146                 names => [ qw/andyg sri mst ash/ ],
 147              } ),
 148
 149         );
 150         # redirect or display a message
 151     }
 152
 153 And the template:
 154
 155     [%- FOREACH name IN names -%]
 156     Hi, [% name %]!
 157     [%- END -%]
 158
 159     --
 160     Regards,
 161     Us
 162
 163 Output:
 164
 165     Hi, andyg!
 166     Hi, sri!
 167     Hi, mst!
 168     Hi, ash!
 169
 170     --
 171     Regards,
 172     Us
 173
 174 =head1 SEE ALSO
 175
 176 L<Catalyst>, L<Catalyst::View::TT>, L<Email::Send>, L<Email::MIME::Creator>
 177
 178 =head1 AUTHOR
 179
 180 Sebastian Riedel, C<sri@cpan.org>
 181
 182 =head1 THANKS
 183
 184 Andy Grundman - Additional documentation
 185
 186 Carl Franks - Additional documentation
 187
 188 =head1 COPYRIGHT
 189
 190 This program is free software, you can redistribute it and/or modify it
 191 under the same terms as Perl itself.
 192
 193 =cut
 194
 195 1;