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                 from    => 'no-reply@foobar.com',
  66                 subject => 'I am a Catalyst generated email',
  67                 body    => 'Body Body Body',
  68             };
  69
  70             $c->forward( $c->view('Email') );
  71         }
  72
  73     Alternatively you can use a more raw interface and specify the headers
  74     as an array reference like it is passed to Email::MIME::Creator. Note
  75     that you may also mix both syntaxes if you like ours better but need to
  76     specify additional header attributes. The attributes are appended to the
  77     header array reference without overwriting contained ones.
  78
  79         $c->stash->{email} = {
  80             header => [
  81                 To      => 'jshirley@gmail.com',
  82                 Cc      => 'abraxxa@cpan.org',
  83                 From    => 'no-reply@foobar.com',
  84                 Subject => 'Note the capitalization differences',
  85             ],
  86             body => qq{Ain't got no body, and nobody cares.},
  87             # Or, send parts
  88             parts => [
  89                 Email::MIME->create(
  90                     attributes => {
  91                         content_type => 'text/plain',
  92                         disposition  => 'attachment',
  93                         charset      => 'US-ASCII',
  94                     },
  95                     body => qq{Got a body, but didn't get ahead.},
  96                 )
  97             ],
  98         };
  99
 100 HANDLING ERRORS
 101     If the email fails to send, the view will die (throw an exception).
 102     After your forward to the view, it is a good idea to check for errors:
 103
 104         $c->forward( $c->view('Email') );
 105
 106         if ( scalar( @{ $c->error } ) ) {
 107             $c->error(0); # Reset the error condition if you need to
 108             $c->response->body('Oh noes!');
 109         } else {
 110             $c->response->body('Email sent A-OK! (At least as far as we can tell)');
 111         }
 112
 113 USING TEMPLATES FOR EMAIL
 114     Now, it's no fun to just send out email using plain strings. Take a look
 115     at Catalyst::View::Email::Template to see how you can use your favourite
 116     template engine to render the mail body.
 117
 118 METHODS
 119     new Validates the base config and creates the Email::Sender::Simple
 120         object for later use by process.
 121
 122     process($c)
 123         The process method does the actual processing when the view is
 124         dispatched to.
 125
 126         This method sets up the email parts and hands off to
 127         Email::Sender::Simple to handle the actual email delivery.
 128
 129     setup_attributes($c, $attr)
 130         Merge attributes with the configured defaults. You can override this
 131         method to return a structure to pass into generate_message which
 132         subsequently passes the return value of this method to
 133         Email::MIME->create under the "attributes" key.
 134
 135     generate_message($c, $attr)
 136         Generate a message part, which should be an Email::MIME object and
 137         return it.
 138
 139         Takes the attributes, merges with the defaults as necessary and
 140         returns a message object.
 141
 142 TROUBLESHOOTING
 143     As with most things computer related, things break. Email even more so.
 144     Typically any errors are going to come from using SMTP as your sending
 145     method, which means that if you are having trouble the first place to
 146     look is at Email::Sender::Transport::SMTP. This module is just a wrapper
 147     for Email::Sender::Simple, so if you get an error on sending, it is
 148     likely from there anyway.
 149
 150     If you are using SMTP and have troubles sending, whether it is
 151     authentication or a very bland "Can't send" message, make sure that you
 152     have Net::SMTP and, if applicable, Net::SMTP::SSL installed.
 153
 154     It is very simple to check that you can connect via Net::SMTP, and if
 155     you do have sending errors the first thing to do is to write a simple
 156     script that attempts to connect. If it works, it is probably something
 157     in your configuration so double check there. If it doesn't, well, keep
 158     modifying the script and/or your mail server configuration until it
 159     does!
 160
 161 SEE ALSO
 162   Catalyst::View::Email::Template - Send fancy template emails with Cat
 163   Catalyst::Manual - The Catalyst Manual
 164   Catalyst::Manual::Cookbook - The Catalyst Cookbook
 165 AUTHORS
 166     J. Shirley <jshirley@gmail.com>
 167
 168     Alexander Hartmaier <abraxxa@cpan.org>
 169
 170 CONTRIBUTORS
 171     (Thanks!)
 172
 173     Matt S Trout
 174
 175     Daniel Westermann-Clark
 176
 177     Simon Elliott <cpan@browsing.co.uk>
 178
 179     Roman Filippov
 180
 181     Lance Brown <lance@bearcircle.net>
 182
 183     Devin Austin <dhoss@cpan.org>
 184
 185     Chris Nehren <apeiron@cpan.org>
 186
 187 COPYRIGHT
 188     Copyright (c) 2007 - 2009 the Catalyst::View::Email "AUTHORS" and
 189     "CONTRIBUTORS" as listed above.
 190
 191 LICENSE
 192     This library is free software, you can redistribute it and/or modify it
 193     under the same terms as Perl itself.
 194