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