1POE::Component::Client:U:sSeMrTPC(o3n)tributed Perl DocuPmOeEn:t:aCtoimopnonent::Client::SMTP(3)
2
6 POE::Component::Client::SMTP - Asynchronous mail sending with POE
7
9 Version 0.22
10
12 PoCoClient::SMTP allows you to send email messages in an asynchronous
13 manner, using POE.
14 Thus your program isn't blocking while busy talking with an (E)SMTP
16 server.
17
19 Warning! The following examples are not complete programs, and aren't
20 designed to be run as full blown applications. Their purpose is to
21 quickly introduce you to the module.
22 For complete examples, check the 'eg' directory that can be found in
24 the distribution's kit.
25 A simple example:
27 # load PoCoClient::SMTP
29 use POE::Component::Client::SMTP;
30 # spawn a session
31 POE::Component::Client::SMTP->send(
32 From => 'foo@baz.com',
33 To => 'john@doe.net',
34 Server => 'relay.mailer.net',
35 SMTP_Success => 'callback_event_for_success',
36 SMTP_Failure => 'callback_event_for_failure',
37 );
38 # and you are all set ;-)
39 A more complex example:
41 # load PoCoClient::SMTP
43 use POE::Component::Client::SMTP;
44 # spawn a session
45 POE::Component::Client::SMTP->send(
46 # Email related parameters
47 From => 'foo@baz.com',
48 To => [
49 'john@doe.net',
50 'andy@zzz.org',
51 'peter@z.net',
52 'george@g.com',
53 ],
54 Body => \$email_body, # here's where your message is stored
55 Server => 'relay.mailer.net',
56 Timeout => 100, # 100 seconds before timeouting
57 # POE related parameters
58 Alias => 'pococlsmtpX',
59 SMTP_Success => 'callback_event_for_success',
60 SMTP_Failure => 'callback_event_for_failure',
61 );
62 # and you are all set ;-)
63
65 Below are the methods this Component has:
66 send
68 This immediately spawns a PoCoClient::SMTP Session and registers itself
69 with the Kernel in order to have its job done. This method may be
70 overhead for sending bulk messages, as after sending one message it
71 gets destroyed. Maybe in the future, there will be a spawn method that
72 will keep the Session around forever, until received a 'shutdown' like
73 event.
74 PARAMETERS
76 There are two kinds of parameters PoCoClient::SMTP supports: Email
78 related parameters and POE related parameters:
79 From This holds the sender's email address
81 Defaults to 'root@localhost', just don't ask why.
83 Note: that the email address has to be a bare email address
85 (johndoe@example.com), not an RFC2822 email address ("John Q.
86 Public" <john.q.public@example.com> (The EveryMan))
87 To This holds a list of recipients. Note that To/CC/BCC fields are
89 separated in your email body. From the SMTP server's point of
90 view (and from this component's too) there is no difference as
91 who is To, who CC and who BCC.
92 The bottom line is: be careful how you construct your email
94 message.
95 Defaults to root@localhost', just don't ask why.
97 Note: that the email address has to be a bare email address
99 (johndoe@example.com), not an RFC2822 email address ("John Q.
100 Public" <john.q.public@example.com> (The EveryMan))
101 Body Here's the meat. This scalar contains the message you are
103 sending composed of Email Fields and the actual message
104 content. You need to construct this by hand or use another
105 module. Which one you use is a matter of taste ;-)))
106 Note that MessageFile and FileHandle take precedense over Body.
108 In case MessageFile or FileHandle are set, Body is discarded.
110 Defaults to an empty mail body.
112 Server Here you specify the relay SMTP server to be used by this
114 component. Currently piping thru sendmail is not supported so
115 you need a SMTP server to actually do the mail delivery (either
116 by storing the mail somewhere on the hard drive, or by relaying
117 to another SMTP server).
118 Defaults to 'localhost'
120 Port Usually SMTP servers bind to port 25. (See /etc/services if you
122 are using a *NIX like O.S.).
123 Sometimes, SMTP servers are set to listen to other ports, in
125 which case you need to set this parameter to the correct value
126 to match your setup.
127 Defaults to 25
129 Timeout Set the timeout for SMTP transactions (seconds).
131 Defaults to 30 seconds
133 MyHostname
135 Hostname to present when sending EHLO/HELO command.
136 Defaults to "localhost"
138 BindAddress
140 This attribute is set when creating the socket connection to
141 the SMTP server. See POE::Wheel::SocketFactory for details.
142 BindPort
144 This attribute is set when creating the socket connection to
145 the SMTP server. See POE::Wheel::SocketFactory for details.
146 Debug Set the debugging level. A value greater than 0 increases the
148 Component's verbosity
149 Defaults to 0
151 Alias In case you have multiple PoCoClient::SMTP Sessions, you'd like
153 to handle them separately, so use Alias to differentiate them.
154 This holds the Session's alias.
156 Defaults to nothing. Internally it refcounts to stay alive.
158 Context You may want to set a context for your
160 POE::Component::Client::SMTP session. This is a scalar.
161 When the caller session receives SMTP_Success or SMTP_Failure
163 event, the context is also passed to it if defined.
164 MessageFile
166 Specify a file name from where the email body is slurped.
167 Note: that you still need to specify the parameters like From,
169 To etc.
170 FileHandle
172 Specify a filehandle from where the email body is slurped.
173 POE::Component::Client::SMTP does only a basic check on the
175 filehandle it obtains from FileHandle value; in case you need
176 to do some more sophisticated checks on the file and
177 filehandle, please do it on your own, and then pass the handle
178 to the component.
179 It is important that the handle is readable so please check
181 that before using it.
182 Note: that you still need to specify the parameters like From,
184 To etc.
185 TransactionLog
187 In case you want to get back the Log between the client and the
188 server, you need to enable this.
189 Defaults to disabled.
191 SMTP_Success
193 Event you want to be called by PoCoClient::SMTP in case of
194 success.
195 Defaults to nothing. This means that the Component will not
197 trigger any event and will silently go away.
198 ARG0 Contains Context if any
200 ARG1 ARG1 Contains the SMTP Transaction log if
202 TransactionLog is enabled, in the form:
203 <- string received from server
204 -> string to be sent to server Note that it is
205 possible the string sent to server may not arrive there
206 ARG1 is undefined if TransactionLog is not enabled
208 SMTP_Failure
210 Event you want to be called by PoCoClient::SMTP in case of
211 failure.
212 You will get back the following information:
214 ARG0 The Context you've set when spawning the component, or
216 undef if no Context specified
217 ARG1 A hash ref that currently has only a key:
219 * SMTP_Server_Error, in this case, the value is the
221 string as returned by the server (the error code should
222 be included too by the server in the string)
223 * Timeout, the value is the amount of seconds the
225 timeout was set to
226 * POE::Wheel::* depending on the wheel that returned
228 error on us ;-) the value is a ref to an array
229 containing ARG0 .. ARG3
230 * Configure, for AUTH misconfiguration
232 * MessageFile_Error for not being able to slurp the
234 contents of the file given to MessageFile, in case the
235 parameter was set.
236 Please note that in case the file is opened
238 successfully and we get an error from the ReadWrite
239 Wheel, then the hash key is 'POE::Wheel::ReadWrite'
240 ARG2 ARG2 Contains the SMTP Transaction log if
242 TransactionLog is enabled, in the form:
243 <- string received from server
244 -> string to be sent to server Note that it is
245 possible the string sent to server may not arrive there
246 ARG2 is undefined if TransactionLog is not enabled
248 ARG3 This contains a single line (scalar) describing the
250 error. It's useful for displaying the error in SMTP
251 clients using PoCo
252 Defaults to nothing. This means that the Component will not
254 trigger any event and will silently go away.
255 Auth ESMTP Authentication
257 Currently supported mechanism: PLAIN
259 If you are interested in implementing other mechanisms, please
261 send me an email, it should be piece of cake.
262 Hash ref with the following fields:
264 mechanism
266 The mechanism to use. Currently only PLAIN auth is
267 supported
268 user User name
270 pass User password
272
274 RFC2821 POE POE::Session
275
277 · Currently the Component sends only HELO to the server, except
278 for when using Auth.
279 · PoCo doesn't keep a list of expected responses from TCP server,
281 which means that in case the Server is responding something
282 during DATA transaction, the PoCo will hapily send the message.
283 Please let me know if this is an issue for someone.
284 Bug Reporting
286 Please report bugs using the project's page interface, at:
287 <https://savannah.nongnu.org/projects/pococlsmtp/>
288 Unified format patches are more than welcome.
290
292 Bare LF characters
293 Note that the SMTP protocol forbids bare LF characters in e-mail
294 messages. PoCoClSMTP doesn't do any checking whether you message is
295 SMTP compliant or not.
296 Most of the SMTP servers in the wild are tolerant with bare LF
298 characters, but you shouldn't count on that.
299 The point is you shouldn't send email messages having bare LF
301 characters. See: http://cr.yp.to/docs/smtplf.html
302
304 ESMTP error codes 1XY are ignored and considered as 2XY codes
305
307 BinGOs for ideas/patches and testing
308 Mike Schroeder for ideas
309
311 George Nistorica, "<ultradm@cpan.org>"
312
314 Copyright 2005 - 2007 George Nistorica, all rights reserved.
315 This program is free software; you can redistribute it and/or modify it
317 under the same terms as Perl itself.
318perl v5.12.0 2009-09-02 POE::Component::Client::SMTP(3)