| Commit | Line | Data |
|---|
| beda8c31 |
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 => { |
| 2f883858 |
43 | host => 'smtp.example.com', # defaults to localhost |
| beda8c31 |
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', |
| beda8c31 |
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', |
| beda8c31 |
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 | |
projects / catagits/Catalyst-View-Email.git / blame