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->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     croak "Can't send mail without recipient"
 106         unless length($email->{To});
 107     $email = Email::MIME->create(%$email);
 108     my $args = $c->config->{email} || [];
 109     my @args = @{$args};
 110     my $class;
 111     unless ( $class = shift @args ) {
 112         $class = 'SMTP';
 113         unshift @args, 'localhost';
 114     }
 115     send $class => $email, @args;
 116 }
 117
 118 =head1 USING WITH A VIEW
 119
 120 A common practice is to handle emails using the same template language used
 121 for HTML pages.  This can be accomplished by pairing this plugin with
 122 L<Catalyst::Plugin::SubRequest>.
 123
 124 Here is a short example of rendering an email from a Template Toolkit source
 125 file.  The call to $c->subreq makes an internal call to the render_email
 126 method just like an external call from a browser.  The request will pass
 127 through the end method to be processed by your View class.
 128
 129     sub send_email : Local {
 130         my ( $self, $c ) = @_;
 131
 132         $c->email(
 133             header => [
 134                 To      => 'me@localhost',
 135                 Subject => 'A TT Email',
 136             ],
 137             body => $c->subreq( '/render_email' ),
 138         );
 139         # redirect or display a message
 140     }
 141
 142     sub render_email : Local {
 143         my ( $self, $c ) = @_;
 144
 145         $c->stash(
 146             names    => [ qw/andyg sri mst/ ],
 147             template => 'email.tt',
 148         );
 149     }
 150
 151 And the template:
 152
 153     [%- FOREACH name IN names -%]
 154     Hi, [% name %]!
 155     [%- END -%]
 156
 157     --
 158     Regards,
 159     Us
 160
 161 Output:
 162
 163     Hi, andyg!
 164     Hi, sri!
 165     Hi, mst!
 166
 167     --
 168     Regards,
 169     Us
 170
 171 =head1 SEE ALSO
 172
 173 L<Catalyst>, L<Catalyst::Plugin::SubRequest>, L<Email::Send>,
 174 L<Email::MIME::Creator>
 175
 176 =head1 AUTHOR
 177
 178 Sebastian Riedel, C<sri@cpan.org>
 179
 180 =head1 THANKS
 181
 182 Andy Grundman - Additional documentation
 183
 184 Carl Franks - Additional documentation
 185
 186 =head1 COPYRIGHT
 187
 188 This program is free software, you can redistribute it and/or modify it
 189 under the same terms as Perl itself.
 190
 191 =cut
 192
 193 1;