lib/Catalyst/View/Email.pm

   1 package Catalyst::View::Email;
   2
   3 use warnings;
   4 use strict;
   5
   6 use Class::C3;
   7 use Carp;
   8
   9 use Email::Send;
  10 use Email::MIME::Creator;
  11
  12 use base qw|Catalyst::View|;
  13
  14 our $VERSION = '0.03';
  15
  16 __PACKAGE__->mk_accessors(qw(sender stash_key content_type mailer));
  17
  18 =head1 NAME
  19
  20 Catalyst::View::Email - Send Email from Catalyst
  21
  22 =head1 SYNOPSIS
  23
  24 This module simply sends out email from a stash key specified in the
  25 configuration settings.
  26
  27 =head1 CONFIGURATION
  28
  29 In your app configuration (example in L<YAML>):
  30
  31     View::Email:
  32         stash_key: email
  33         content_type: text/plain
  34         sender:
  35             method:     SMTP
  36             # mailer_args is passed directly into Email::Send
  37             mailer_args:
  38                 - Host:       smtp.example.com
  39                 - username:   username
  40                 - password:   password
  41
  42 =cut
  43
  44 __PACKAGE__->config(
  45     stash_key => 'email',
  46 );
  47
  48 =head1 SENDING EMAIL
  49
  50 In your controller, simply forward to the view after populating the C<stash_key>
  51
  52     sub controller : Private {
  53         my ( $self, $c ) = @_;
  54         $c->stash->{email} = {
  55             to      => q{catalyst@rocksyoursocks.com},
  56             from    => q{no-reply@socksthatarerocked.com},
  57             subject => qq{Your Subject Here},
  58             body    => qq{Body Body Body}
  59         };
  60         $c->forward('View::Email');
  61     }
  62
  63 Alternatively, you can use a more raw interface, and specify the headers as
  64 an array reference.
  65
  66     $c->stash->{email} = {
  67         header => [
  68             To      => 'foo@bar.com',
  69             Subject => 'Note the capitalization differences'
  70         ],
  71         body => qq{Ain't got no body, and nobody cares.},
  72         # Or, send parts
  73         parts => [
  74             Email::MIME->create(
  75                 attributes => {
  76                     content_type => 'text/plain',
  77                     disposition  => 'attachment',
  78                     charset      => 'US-ASCII',
  79                 },
  80                 body => qq{Got a body, but didn't get ahead.}
  81             )
  82         ],
  83     };
  84
  85 =head1 HANDLING FAILURES
  86
  87 If the email fails to send, the view will die (throw an exception).  After
  88 your forward to the view, it is a good idea to check for errors:
  89
  90     $c->forward('View::Email');
  91     if ( scalar( @{ $c->error } ) ) {
  92         $c->error(0); # Reset the error condition if you need to
  93         $c->res->body('Oh noes!');
  94     } else {
  95         $c->res->body('Email sent A-OK! (At least as far as we can tell)');
  96     }
  97
  98 =head1 OTHER MAILERS
  99
 100 Now, it's no fun to just send out email using plain strings.  We also
 101 have L<Catalyst::View::Email::Template> for use.  You can also toggle
 102 this as being used by setting up your configuration to look like this:
 103
 104     View::Email:
 105         default_view: TT
 106
 107 Then, Catalyst::View::Email will forward to your View::TT by default.
 108
 109 =cut
 110
 111 sub new {
 112     my $self = shift->next::method(@_);
 113
 114     my ( $c, $arguments ) = @_;
 115
 116     my $mailer = Email::Send->new;
 117
 118     if ( my $method = $self->sender->{method} ) {
 119         croak "$method is not supported, see Email::Send"
 120             unless $mailer->mailer_available($method);
 121         $mailer->mailer($method);
 122     } else {
 123         # Default case, run through the most likely options first.
 124         for ( qw/SMTP Sendmail Qmail/ ) {
 125             $mailer->mailer($_) and last if $mailer->mailer_available($_);
 126         }
 127     }
 128
 129     if ( $self->sender->{mailer_args} ) {
 130         $mailer->mailer_args($self->sender->{mailer_args});
 131     }
 132
 133     $self->mailer($mailer);
 134
 135     return $self;
 136 }
 137
 138 sub process {
 139     my ( $self, $c ) = @_;
 140
 141     croak "Unable to send mail, bad mail configuration"
 142         unless $self->mailer;
 143
 144     my $email  = $c->stash->{$self->stash_key};
 145     croak "Can't send email without a valid email structure"
 146         unless $email;
 147
 148     if ( $self->content_type ) {
 149         $email->{content_type} ||= $self->content_type;
 150     }
 151
 152     my $header  = $email->{header} || [];
 153         push @$header, ('To' => delete $email->{to})
 154             if $email->{to};
 155         push @$header, ('From' => delete $email->{from})
 156             if $email->{from};
 157         push @$header, ('Subject' => delete $email->{subject})
 158             if $email->{subject};
 159         push @$header, ('Content-type' => delete $email->{content_type})
 160             if $email->{content_type};
 161
 162     my $parts = $email->{parts};
 163     my $body  = $email->{body};
 164
 165     unless ( $parts or $body ) {
 166         croak "Can't send email without parts or body, check stash";
 167     }
 168
 169     my %mime = ( header => $header );
 170
 171     if ( $parts and ref $parts eq 'ARRAY' ) {
 172         $mime{parts} = $parts;
 173     } else {
 174         $mime{body} = $body;
 175     }
 176
 177     my $message = Email::MIME->create(%mime);
 178
 179     if ( $message ) {
 180         $self->mailer->send($message);
 181     } else {
 182         croak "Unable to create message";
 183     }
 184 }
 185
 186 =head1 SEE ALSO
 187
 188 =head2 L<Catalyst::View::Email::Template> - Send fancy template emails with Cat
 189
 190 =head2 L<Catalyst::Manual> - The Catalyst Manual
 191
 192 =head2 L<Catalyst::Manual::Cookbook> - The Catalyst Cookbook
 193
 194 =head1 AUTHORS
 195
 196 J. Shirley <jshirley@gmail.com>
 197
 198 =head1 CONTRIBUTORS
 199
 200 (Thanks!)
 201
 202 Matt S Trout
 203
 204 Daniel Westermann-Clark
 205
 206 =head1 LICENSE
 207
 208 This library is free software, you can redistribute it and/or modify it under
 209 the same terms as Perl itself.
 210
 211 =cut
 212
 213 1;