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.07';
  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.  This can be accomplished by pairing this plugin with
 120 L<Catalyst::Plugin::SubRequest>.
 121
 122 Here is a short example of rendering an email from a Template Toolkit source
 123 file.  The call to $c->subreq makes an internal call to the render_email
 124 method just like an external call from a browser.  The request will pass
 125 through the end method to be processed by your View class.
 126
 127     sub send_email : Local {
 128         my ( $self, $c ) = @_;
 129
 130         $c->email(
 131             header => [
 132                 To      => 'me@localhost',
 133                 Subject => 'A TT Email',
 134             ],
 135             body => $c->subreq( '/render_email' ),
 136         );
 137         # redirect or display a message
 138     }
 139
 140     sub render_email : Local {
 141         my ( $self, $c ) = @_;
 142
 143         $c->stash(
 144             names    => [ qw/andyg sri mst/ ],
 145             template => 'email.tt',
 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
 178 =head1 THANKS
 179
 180 Andy Grundman - Additional documentation
 181
 182 Carl Franks - Additional documentation
 183
 184 =head1 COPYRIGHT
 185
 186 This program is free software, you can redistribute it and/or modify it
 187 under the same terms as Perl itself.
 188
 189 =cut
 190
 191 1;