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