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