1POE::Component::Client:U:sSeMrTPC(o3n)tributed Perl DocuPmOeEn:t:aCtoimopnonent::Client::SMTP(3)
2
3
4

NAME

6       POE::Component::Client::SMTP - Asynchronous mail sending with POE
7

VERSION

9       Version 0.22
10

DESCRIPTION

12       PoCoClient::SMTP allows you to send email messages in an asynchronous
13       manner, using POE.
14
15       Thus your program isn't blocking while busy talking with an (E)SMTP
16       server.
17

SYNOPSIS

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
23       For complete examples, check the 'eg' directory that can be found in
24       the distribution's kit.
25
26       A simple example:
27
28        # 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
40       A more complex example:
41
42        # 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

METHODS

65       Below are the methods this Component has:
66
67   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
75       PARAMETERS
76
77       There are two kinds of parameters PoCoClient::SMTP supports: Email
78       related parameters and POE related parameters:
79
80       From    This holds the sender's email address
81
82               Defaults to 'root@localhost', just don't ask why.
83
84               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
88       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
93               The bottom line is: be careful how you construct your email
94               message.
95
96               Defaults to root@localhost', just don't ask why.
97
98               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
102       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
107               Note that MessageFile and FileHandle take precedense over Body.
108
109               In case MessageFile or FileHandle are set, Body is discarded.
110
111               Defaults to an empty mail body.
112
113       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
119               Defaults to 'localhost'
120
121       Port    Usually SMTP servers bind to port 25. (See /etc/services if you
122               are using a *NIX like O.S.).
123
124               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
128               Defaults to 25
129
130       Timeout Set the timeout for SMTP transactions (seconds).
131
132               Defaults to 30 seconds
133
134       MyHostname
135               Hostname to present when sending EHLO/HELO command.
136
137               Defaults to "localhost"
138
139       BindAddress
140               This attribute is set when creating the socket connection to
141               the SMTP server.  See POE::Wheel::SocketFactory for details.
142
143       BindPort
144               This attribute is set when creating the socket connection to
145               the SMTP server.  See POE::Wheel::SocketFactory for details.
146
147       Debug   Set the debugging level. A value greater than 0 increases the
148               Component's verbosity
149
150               Defaults to 0
151
152       Alias   In case you have multiple PoCoClient::SMTP Sessions, you'd like
153               to handle them separately, so use Alias to differentiate them.
154
155               This holds the Session's alias.
156
157               Defaults to nothing. Internally it refcounts to stay alive.
158
159       Context You may want to set a context for your
160               POE::Component::Client::SMTP session.  This is a scalar.
161
162               When the caller session receives SMTP_Success or SMTP_Failure
163               event, the context is also passed to it if defined.
164
165       MessageFile
166               Specify a file name from where the email body is slurped.
167
168               Note: that you still need to specify the parameters like From,
169               To etc.
170
171       FileHandle
172               Specify a filehandle from where the email body is slurped.
173
174               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
180               It is important that the handle is readable so please check
181               that before using it.
182
183               Note: that you still need to specify the parameters like From,
184               To etc.
185
186       TransactionLog
187               In case you want to get back the Log between the client and the
188               server, you need to enable this.
189
190               Defaults to disabled.
191
192       SMTP_Success
193               Event you want to be called by PoCoClient::SMTP in case of
194               success.
195
196               Defaults to nothing. This means that the Component will not
197               trigger any event and will silently go away.
198
199               ARG0    Contains Context if any
200
201               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
207                       ARG1 is undefined if TransactionLog is not enabled
208
209       SMTP_Failure
210               Event you want to be called by PoCoClient::SMTP in case of
211               failure.
212
213               You will get back the following information:
214
215               ARG0    The Context you've set when spawning the component, or
216                       undef if no Context specified
217
218               ARG1    A hash ref that currently has only a key:
219
220                       * 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
224                       * Timeout, the value is the amount of seconds the
225                       timeout was set to
226
227                       * 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
231                       * Configure, for AUTH misconfiguration
232
233                       * 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
237                       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
241               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
247                       ARG2 is undefined if TransactionLog is not enabled
248
249               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
253               Defaults to nothing. This means that the Component will not
254               trigger any event and will silently go away.
255
256       Auth    ESMTP Authentication
257
258               Currently supported mechanism: PLAIN
259
260               If you are interested in implementing other mechanisms, please
261               send me an email, it should be piece of cake.
262
263               Hash ref with the following fields:
264
265               mechanism
266                       The mechanism to use. Currently only PLAIN auth is
267                       supported
268
269               user    User name
270
271               pass    User password
272

SEE ALSO

274       RFC2821 POE POE::Session
275

BUGS

277       ·       Currently the Component sends only HELO to the server, except
278               for when using Auth.
279
280       ·       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
285   Bug Reporting
286       Please report bugs using the project's page interface, at:
287       <https://savannah.nongnu.org/projects/pococlsmtp/>
288
289       Unified format patches are more than welcome.
290

KNOWN ISSUES

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
297       Most of the SMTP servers in the wild are tolerant with bare LF
298       characters, but you shouldn't count on that.
299
300       The point is you shouldn't send email messages having bare LF
301       characters.  See: http://cr.yp.to/docs/smtplf.html
302

ESMTP error codes 1XY

304       ESMTP error codes 1XY are ignored and considered as 2XY codes
305

ACKNOWLEDGMENTS

307       BinGOs for ideas/patches and testing
308       Mike Schroeder for ideas
309

AUTHOR

311       George Nistorica, "<ultradm@cpan.org>"
312
314       Copyright 2005 - 2007 George Nistorica, all rights reserved.
315
316       This program is free software; you can redistribute it and/or modify it
317       under the same terms as Perl itself.
318
319
320
321perl v5.12.0                      2009-09-02   POE::Component::Client::SMTP(3)
Impressum