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