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