README

   1 NAME
   2     Catalyst::View::Email - Send Email from Catalyst
   3
   4 SYNOPSIS
   5     This module sends out emails from a stash key specified in the
   6     configuration settings.
   7
   8 CONFIGURATION
   9     WARNING: since version 0.10 the configuration options slightly changed!
  10
  11     Use the helper to create your View:
  12
  13         $ script/myapp_create.pl view Email Email
  14
  15     In your app configuration:
  16
  17         __PACKAGE__->config(
  18             'View::Email' => {
  19                 # Where to look in the stash for the email information.
  20                 # 'email' is the default, so you don't have to specify it.
  21                 stash_key => 'email',
  22                 # Define the defaults for the mail
  23                 default => {
  24                     # Defines the default content type (mime type). Mandatory
  25                     content_type => 'text/plain',
  26                     # Defines the default charset for every MIME part with the
  27                     # content type text.
  28                     # According to RFC2049 a MIME part without a charset should
  29                     # be treated as US-ASCII by the mail client.
  30                     # If the charset is not set it won't be set for all MIME parts
  31                     # without an overridden one.
  32                     # Default: none
  33                     charset => 'utf-8'
  34                 },
  35                 # Setup how to send the email
  36                 # all those options are passed directly to Email::Sender::Simple
  37                 sender => {
  38                     # if mailer doesn't start with Email::Sender::Simple::Transport::,
  39                     # then this is prepended.
  40                     mailer => 'SMTP',
  41                     # mailer_args is passed directly into Email::Sender::Simple
  42                     mailer_args => {
  43                         host     => 'smtp.example.com', # defaults to localhost
  44                         username => 'username',
  45                         password => 'password',
  46                 }
  47               }
  48             }
  49         );
  50
  51 NOTE ON SMTP
  52     If you use SMTP and don't specify host, it will default to localhost and
  53     attempt delivery. This often means an email will sit in a queue and not
  54     be delivered.
  55
  56 SENDING EMAIL
  57     Sending email is just filling the stash and forwarding to the view:
  58
  59         sub controller : Private {
  60             my ( $self, $c ) = @_;
  61
  62             $c->stash->{email} = {
  63                 to      => 'jshirley@gmail.com',
  64                 cc      => 'abraxxa@cpan.org',
  65                 bcc     => join ',', qw/hidden@secret.com hidden2@foobar.com/,
  66                 from    => 'no-reply@foobar.com',
  67                 subject => 'I am a Catalyst generated email',
  68                 body    => 'Body Body Body',
  69             };
  70
  71             $c->forward( $c->view('Email') );
  72         }
  73
  74     Alternatively you can use a more raw interface and specify the headers
  75     as an array reference like it is passed to Email::MIME::Creator. Note
  76     that you may also mix both syntaxes if you like ours better but need to
  77     specify additional header attributes. The attributes are appended to the
  78     header array reference without overwriting contained ones.
  79
  80         $c->stash->{email} = {
  81             header => [
  82                 To      => 'jshirley@gmail.com',
  83                 Cc      => 'abraxxa@cpan.org',
  84                 Bcc     => join ',', qw/hidden@secret.com hidden2@foobar.com/,
  85                 From    => 'no-reply@foobar.com',
  86                 Subject => 'Note the capitalization differences',
  87             ],
  88             body => qq{Ain't got no body, and nobody cares.},
  89             # Or, send parts
  90             parts => [
  91                 Email::MIME->create(
  92                     attributes => {
  93                         content_type => 'text/plain',
  94                         disposition  => 'attachment',
  95                         charset      => 'US-ASCII',
  96                     },
  97                     body => qq{Got a body, but didn't get ahead.},
  98                 )
  99             ],
 100         };
 101
 102 HANDLING ERRORS
 103     If the email fails to send, the view will die (throw an exception).
 104     After your forward to the view, it is a good idea to check for errors:
 105
 106         $c->forward( $c->view('Email') );
 107
 108         if ( scalar( @{ $c->error } ) ) {
 109             $c->error(0); # Reset the error condition if you need to
 110             $c->response->body('Oh noes!');
 111         } else {
 112             $c->response->body('Email sent A-OK! (At least as far as we can tell)');
 113         }
 114
 115 USING TEMPLATES FOR EMAIL
 116     Now, it's no fun to just send out email using plain strings. Take a look
 117     at Catalyst::View::Email::Template to see how you can use your favourite
 118     template engine to render the mail body.
 119
 120 METHODS
 121     new Validates the base config and creates the Email::Sender::Simple
 122         object for later use by process.
 123
 124     process($c)
 125         The process method does the actual processing when the view is
 126         dispatched to.
 127
 128         This method sets up the email parts and hands off to
 129         Email::Sender::Simple to handle the actual email delivery.
 130
 131     setup_attributes($c, $attr)
 132         Merge attributes with the configured defaults. You can override this
 133         method to return a structure to pass into generate_message which
 134         subsequently passes the return value of this method to
 135         Email::MIME->create under the "attributes" key.
 136
 137     generate_message($c, $attr)
 138         Generate a message part, which should be an Email::MIME object and
 139         return it.
 140
 141         Takes the attributes, merges with the defaults as necessary and
 142         returns a message object.
 143
 144 TROUBLESHOOTING
 145     As with most things computer related, things break. Email even more so.
 146     Typically any errors are going to come from using SMTP as your sending
 147     method, which means that if you are having trouble the first place to
 148     look is at Email::Sender::Transport::SMTP. This module is just a wrapper
 149     for Email::Sender::Simple, so if you get an error on sending, it is
 150     likely from there anyway.
 151
 152     If you are using SMTP and have troubles sending, whether it is
 153     authentication or a very bland "Can't send" message, make sure that you
 154     have Net::SMTP and, if applicable, Net::SMTP::SSL installed.
 155
 156     It is very simple to check that you can connect via Net::SMTP, and if
 157     you do have sending errors the first thing to do is to write a simple
 158     script that attempts to connect. If it works, it is probably something
 159     in your configuration so double check there. If it doesn't, well, keep
 160     modifying the script and/or your mail server configuration until it
 161     does!
 162
 163 SEE ALSO
 164   Catalyst::View::Email::Template - Send fancy template emails with Cat
 165   Catalyst::Manual - The Catalyst Manual
 166   Catalyst::Manual::Cookbook - The Catalyst Cookbook
 167 AUTHORS
 168     J. Shirley <jshirley@gmail.com>
 169
 170     Alexander Hartmaier <abraxxa@cpan.org>
 171
 172 CONTRIBUTORS
 173     (Thanks!)
 174
 175     Matt S Trout
 176
 177     Daniel Westermann-Clark
 178
 179     Simon Elliott <cpan@browsing.co.uk>
 180
 181     Roman Filippov
 182
 183     Lance Brown <lance@bearcircle.net>
 184
 185     Devin Austin <dhoss@cpan.org>
 186
 187     Chris Nehren <apeiron@cpan.org>
 188
 189 COPYRIGHT
 190     Copyright (c) 2007 - 2009 the Catalyst::View::Email "AUTHORS" and
 191     "CONTRIBUTORS" as listed above.
 192
 193 LICENSE
 194     This library is free software, you can redistribute it and/or modify it
 195     under the same terms as Perl itself.
 196