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 - (DEPRECATED) Send emails with Catalyst
  14
  15 =head1 SYNOPSIS
  16
  17     # please use Email::MIME::Kit or Catalyst::View::Email::Template instead
  18
  19     use Catalyst 'Email';
  20
  21     __PACKAGE__->config->{email} = [qw/SMTP smtp.oook.de/];
  22
  23     $c->email(
  24         header => [
  25             From    => 'sri@oook.de',
  26             To      => 'sri@cpan.org',
  27             Subject => 'Hello!'
  28         ],
  29         body => 'Hello sri'
  30     );
  31
  32 =head1 DESCRIPTION
  33
  34 Send emails with Catalyst and L<Email::Send> and L<Email::MIME::Creator>.
  35
  36 =head1 CONFIGURATION
  37
  38 C<config> accepts the same options as L<Email::Send>.
  39
  40 To send using the system's C<sendmail> program, set C<config> like so:
  41
  42     __PACKAGE__->config->{email} = ['Sendmail'];
  43
  44 To send using authenticated SMTP:
  45
  46     __PACKAGE__->config->{email} = [
  47         'SMTP',
  48         'smtp.myhost.com',
  49         username => $USERNAME,
  50         password => $PASSWORD,
  51     ];
  52
  53 For different methods of sending emails, and appropriate C<config> options,
  54 see L<Email::Send::NNTP>, L<Email::Send::Qmail>, L<Email::Send::SMTP> and
  55 L<Email::Send::Sendmail>.
  56
  57 =head1 METHODS
  58
  59 =head2 email
  60
  61 C<email()> accepts the same arguments as L<Email::MIME::Creator>'s
  62 C<create()>.
  63
  64     $c->email(
  65         header => [
  66             To      => 'me@localhost',
  67             Subject => 'A TT Email',
  68         ],
  69         body => $c->subreq( '/render_email' ),
  70     );
  71
  72 To send a multipart message, include a C<parts> argument containing an
  73 arrayref of Email::MIME objects.
  74
  75     my @parts = (
  76         Email::MIME->create(
  77             attributes => {
  78                 content_type => 'application/pdf',
  79                 encoding     => 'quoted-printable',
  80                 name         => 'report.pdf',
  81             },
  82             body => $FILE_DATA,
  83         ),
  84         Email::MIME->create(
  85             attributes => {
  86                 content_type => 'text/plain',
  87                 disposition  => 'attachment',
  88                 charset      => 'US-ASCII',
  89             },
  90             body => $c->subreq( '/render_email' ),
  91         ),
  92     );
  93
  94     $c->email(
  95         header => [
  96             To      => 'me@localhost',
  97             Subject => 'A TT Email',
  98         ],
  99         parts => \@parts,
 100     );
 101
 102 =cut
 103
 104 sub email {
 105     my $c = shift;
 106     my $email = $_[1] ? {@_} : $_[0];
 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.  If your view supports the 'render' method (Like the TT view
 122 does), you just set the body like this:
 123   $c->email(
 124      header => [
 125         To      => 'me@localhost',
 126         Subject => 'A TT Email',
 127      ],
 128      body => $c->view('TT')->render($c,'mytemplate.tt'),
 129   }
 130
 131 If your view doesn't support render, you can just forward to it, then reset
 132 the body like this:
 133
 134     sub send_email : Local {
 135         my ( $self, $c ) = @_;
 136         {
 137         local $c->stash->{names}   = [ qw/andyg sri mst/ ],
 138         local $c->stash->{template}= 'mytemplate.tt';
 139         $c->forward($c->view('MyView'));
 140         $c->email(
 141             header => [
 142                 To      => 'me@localhost',
 143                 Subject => 'A TT Email',
 144             ],
 145             body => $c->res->body,
 146         );
 147         $c->res->body(undef);
 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 Andy Grundman
 180 Carl Franks
 181 Marcus Ramberg C<mramberg@cpan.org>
 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;