Commit | Line | Data |
20099de7 |
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 => { |
c13800f7 |
43 | Host => 'smtp.example.com', # defaults to localhost |
20099de7 |
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 |
1bad2eb3 |
148 | look is at Email::Sender::Transport::SMTP. This module is just a wrapper |
20099de7 |
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 | |