lib/Catalyst/Plugin/Email.pm

   1 package Catalyst::Plugin::Email;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Email::Send;
   7 use Email::MIME;
   8 use Email::MIME::Creator;
   9
  10 our $VERSION = '0.09';
  11
  12 =head1 NAME
  13
  14 Catalyst::Plugin::Email - (DEPRECATED) Send emails with Catalyst
  15
  16 =head1 SYNOPSIS
  17
  18     # please use Email::MIME::Kit or Catalyst::View::Email::Template instead
  19
  20     use Catalyst 'Email';
  21
  22     __PACKAGE__->config->{email} = [qw/SMTP smtp.oook.de/];
  23
  24     $c->email(
  25         header => [
  26             From    => 'sri@oook.de',
  27             To      => 'sri@cpan.org',
  28             Subject => 'Hello!'
  29         ],
  30         body => 'Hello sri'
  31     );
  32
  33 =head1 DESCRIPTION
  34
  35 Send emails with Catalyst and L<Email::Send> and L<Email::MIME::Creator>.
  36
  37 =head1 CONFIGURATION
  38
  39 C<config> accepts the same options as L<Email::Send>.
  40
  41 To send using the system's C<sendmail> program, set C<config> like so:
  42
  43     __PACKAGE__->config->{email} = ['Sendmail'];
  44
  45 To send using authenticated SMTP:
  46
  47     __PACKAGE__->config->{email} = [
  48         'SMTP',
  49         'smtp.myhost.com',
  50         username => $USERNAME,
  51         password => $PASSWORD,
  52     ];
  53
  54 For different methods of sending emails, and appropriate C<config> options,
  55 see L<Email::Send::NNTP>, L<Email::Send::Qmail>, L<Email::Send::SMTP> and
  56 L<Email::Send::Sendmail>.
  57
  58 =head1 METHODS
  59
  60 =head2 email
  61
  62 C<email()> accepts the same arguments as L<Email::MIME::Creator>'s
  63 C<create()>.
  64
  65     $c->email(
  66         header => [
  67             To      => 'me@localhost',
  68             Subject => 'A TT Email',
  69         ],
  70         body => $c->subreq( '/render_email' ),
  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->subreq( '/render_email' ),
  92         ),
  93     );
  94
  95     $c->email(
  96         header => [
  97             To      => 'me@localhost',
  98             Subject => 'A TT Email',
  99         ],
 100         parts => \@parts,
 101     );
 102
 103 =cut
 104
 105 sub email {
 106     my $c = shift;
 107     my $email = $_[1] ? {@_} : $_[0];
 108     $email = Email::MIME->create(%$email);
 109     my $args = $c->config->{email} || [];
 110     my @args = @{$args};
 111     my $class;
 112     unless ( $class = shift @args ) {
 113         $class = 'SMTP';
 114         unshift @args, 'localhost';
 115     }
 116     send $class => $email, @args;
 117 }
 118
 119 =head1 USING WITH A VIEW
 120
 121 A common practice is to handle emails using the same template language used
 122 for HTML pages.  If your view supports the 'render' method (Like the TT view
 123 does), you just set the body like this:
 124   $c->email(
 125      header => [
 126         To      => 'me@localhost',
 127         Subject => 'A TT Email',
 128      ],
 129      body => $c->view('TT')->render($c,'mytemplate.tt'),
 130   }
 131
 132 If your view doesn't support render, you can just forward to it, then reset
 133 the body like this:
 134
 135     sub send_email : Local {
 136         my ( $self, $c ) = @_;
 137         {
 138         local $c->stash->{names}   = [ qw/andyg sri mst/ ],
 139         local $c->stash->{template}= 'mytemplate.tt';
 140         $c->forward($c->view('MyView'));
 141         $c->email(
 142             header => [
 143                 To      => 'me@localhost',
 144                 Subject => 'A TT Email',
 145             ],
 146             body => $c->res->body,
 147         );
 148         $c->res->body(undef);
 149         }
 150     }
 151
 152 And the template:
 153
 154     [%- FOREACH name IN names -%]
 155     Hi, [% name %]!
 156     [%- END -%]
 157
 158     --
 159     Regards,
 160     Us
 161
 162 Output:
 163
 164     Hi, andyg!
 165     Hi, sri!
 166     Hi, mst!
 167
 168     --
 169     Regards,
 170     Us
 171
 172 =head1 SEE ALSO
 173
 174 L<Catalyst>, L<Catalyst::Plugin::SubRequest>, L<Email::Send>,
 175 L<Email::MIME::Creator>
 176
 177 =head1 AUTHOR
 178
 179 Sebastian Riedel, C<sri@cpan.org>
 180 Andy Grundman
 181 Carl Franks
 182 Marcus Ramberg C<mramberg@cpan.org>
 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;