1Catalyst::View::Email(3U)ser Contributed Perl DocumentatiCoantalyst::View::Email(3)
2
3
4

NAME

6       Catalyst::View::Email - Send Email from Catalyst
7

SYNOPSIS

9       This module sends out emails from a stash key specified in the
10       configuration settings.
11

CONFIGURATION

13       WARNING: since version 0.10 the configuration options slightly changed!
14
15       Use the helper to create your View:
16
17           $ script/myapp_create.pl view Email Email
18
19       In your app configuration:
20
21           __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

NOTE ON SMTP

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

SENDING EMAIL

61       Sending email is just filling the stash and forwarding to the view:
62
63           sub controller : Private {
64               my ( $self, $c ) = @_;
65
66               $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
74               $c->forward( $c->view('Email') );
75           }
76
77       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
83           $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
105       You can set the envelope sender and recipient as well:
106
107         $c->stash->{email} = {
108
109           envelope_from => 'envelope-from@example.com',
110           from          => 'header-from@example.com',
111
112           envelope_to   => [ 'foo@example.com', 'bar@example.com' ],
113           to            => 'Undisclosed Recipients:;',
114
115           ...
116         };
117

HANDLING ERRORS

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
122           $c->forward( $c->view('Email') );
123
124           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

USING TEMPLATES FOR EMAIL

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

METHODS

137       new Validates the base config and creates the Email::Sender::Simple
138           object for later use by process.
139
140       process($c)
141           The process method does the actual processing when the view is
142           dispatched to.
143
144           This method sets up the email parts and hands off to
145           Email::Sender::Simple to handle the actual email delivery.
146
147       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
153       generate_message($c, $attr)
154           Generate a message part, which should be an Email::MIME object and
155           return it.
156
157           Takes the attributes, merges with the defaults as necessary and
158           returns a message object.
159

TROUBLESHOOTING

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
168       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
172       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

SEE ALSO

180   Catalyst::View::Email::Template - Send fancy template emails with Cat
181   Catalyst::Manual - The Catalyst Manual
182   Catalyst::Manual::Cookbook - The Catalyst Cookbook

AUTHORS

184       J. Shirley <jshirley@gmail.com>
185
186       Alexander Hartmaier <abraxxa@cpan.org>
187

CONTRIBUTORS

189       (Thanks!)
190
191       Matt S Trout
192
193       Daniel Westermann-Clark
194
195       Simon Elliott <cpan@browsing.co.uk>
196
197       Roman Filippov
198
199       Lance Brown <lance@bearcircle.net>
200
201       Devin Austin <dhoss@cpan.org>
202
203       Chris Nehren <apeiron@cpan.org>
204
206       Copyright (c) 2007 - 2009 the Catalyst::View::Email "AUTHORS" and
207       "CONTRIBUTORS" as listed above.
208

LICENSE

210       This library is free software, you can redistribute it and/or modify it
211       under the same terms as Perl itself.
212
213
214
215perl v5.32.1                      2021-01-26          Catalyst::View::Email(3)
Impressum