POE::Component::ClientUserTContributed Perl DocPOE::Component::Client::SMTP(3)NAMEPOE::Component::Client::SMTP - Asynchronous mail sending with POE
VERSION
Version 0.22
DESCRIPTION
PoCoClient::SMTP allows you to send email messages in an asynchronous
manner, using POE.
Thus your program isn't blocking while busy talking with an (E)SMTP
server.
SYNOPSIS
Warning! The following examples are not complete programs, and aren't
designed to be run as full blown applications. Their purpose is to
quickly introduce you to the module.
For complete examples, check the 'eg' directory that can be found in
the distribution's kit.
A simple example:
# load PoCoClient::SMTP
use POE::Component::Client::SMTP;
# spawn a session
POE::Component::Client::SMTP->send(
From => 'foo@baz.com',
To => 'john@doe.net',
Server => 'relay.mailer.net',
SMTP_Success => 'callback_event_for_success',
SMTP_Failure => 'callback_event_for_failure',
);
# and you are all set ;-)
A more complex example:
# load PoCoClient::SMTP
use POE::Component::Client::SMTP;
# spawn a session
POE::Component::Client::SMTP->send(
# Email related parameters
From => 'foo@baz.com',
To => [
'john@doe.net',
'andy@zzz.org',
'peter@z.net',
'george@g.com',
],
Body => \$email_body, # here's where your message is stored
Server => 'relay.mailer.net',
Timeout => 100, # 100 seconds before timeouting
# POE related parameters
Alias => 'pococlsmtpX',
SMTP_Success => 'callback_event_for_success',
SMTP_Failure => 'callback_event_for_failure',
);
# and you are all set ;-)
METHODS
Below are the methods this Component has:
send
This immediately spawns a PoCoClient::SMTP Session and registers itself
with the Kernel in order to have its job done. This method may be
overhead for sending bulk messages, as after sending one message it
gets destroyed. Maybe in the future, there will be a spawn method that
will keep the Session around forever, until received a 'shutdown' like
event.
PARAMETERS
There are two kinds of parameters PoCoClient::SMTP supports: Email
related parameters and POE related parameters:
From This holds the sender's email address
Defaults to 'root@localhost', just don't ask why.
Note: that the email address has to be a bare email address
(johndoe@example.com), not an RFC2822 email address ("John Q.
Public" <john.q.public@example.com> (The EveryMan))
To This holds a list of recipients. Note that To/CC/BCC fields are
separated in your email body. From the SMTP server's point of
view (and from this component's too) there is no difference as
who is To, who CC and who BCC.
The bottom line is: be careful how you construct your email
message.
Defaults to root@localhost', just don't ask why.
Note: that the email address has to be a bare email address
(johndoe@example.com), not an RFC2822 email address ("John Q.
Public" <john.q.public@example.com> (The EveryMan))
Body Here's the meat. This scalar contains the message you are
sending composed of Email Fields and the actual message
content. You need to construct this by hand or use another
module. Which one you use is a matter of taste ;-)))
Note that MessageFile and FileHandle take precedense over Body.
In case MessageFile or FileHandle are set, Body is discarded.
Defaults to an empty mail body.
Server Here you specify the relay SMTP server to be used by this
component. Currently piping thru sendmail is not supported so
you need a SMTP server to actually do the mail delivery (either
by storing the mail somewhere on the hard drive, or by relaying
to another SMTP server).
Defaults to 'localhost'
Port Usually SMTP servers bind to port 25. (See /etc/services if you
are using a *NIX like O.S.).
Sometimes, SMTP servers are set to listen to other ports, in
which case you need to set this parameter to the correct value
to match your setup.
Defaults to 25
Timeout Set the timeout for SMTP transactions (seconds).
Defaults to 30 seconds
MyHostname
Hostname to present when sending EHLO/HELO command.
Defaults to "localhost"
BindAddress
This attribute is set when creating the socket connection to
the SMTP server. See POE::Wheel::SocketFactory for details.
BindPort
This attribute is set when creating the socket connection to
the SMTP server. See POE::Wheel::SocketFactory for details.
Debug Set the debugging level. A value greater than 0 increases the
Component's verbosity
Defaults to 0
Alias In case you have multiple PoCoClient::SMTP Sessions, you'd like
to handle them separately, so use Alias to differentiate them.
This holds the Session's alias.
Defaults to nothing. Internally it refcounts to stay alive.
Context You may want to set a context for your
POE::Component::Client::SMTP session. This is a scalar.
When the caller session receives SMTP_Success or SMTP_Failure
event, the context is also passed to it if defined.
MessageFile
Specify a file name from where the email body is slurped.
Note: that you still need to specify the parameters like From,
To etc.
FileHandle
Specify a filehandle from where the email body is slurped.
POE::Component::Client::SMTP does only a basic check on the
filehandle it obtains from FileHandle value; in case you need
to do some more sophisticated checks on the file and
filehandle, please do it on your own, and then pass the handle
to the component.
It is important that the handle is readable so please check
that before using it.
Note: that you still need to specify the parameters like From,
To etc.
TransactionLog
In case you want to get back the Log between the client and the
server, you need to enable this.
Defaults to disabled.
SMTP_Success
Event you want to be called by PoCoClient::SMTP in case of
success.
Defaults to nothing. This means that the Component will not
trigger any event and will silently go away.
ARG0 Contains Context if any
ARG1 ARG1 Contains the SMTP Transaction log if
TransactionLog is enabled, in the form:
<- string received from server
-> string to be sent to server Note that it is
possible the string sent to server may not arrive there
ARG1 is undefined if TransactionLog is not enabled
SMTP_Failure
Event you want to be called by PoCoClient::SMTP in case of
failure.
You will get back the following information:
ARG0 The Context you've set when spawning the component, or
undef if no Context specified
ARG1 A hash ref that currently has only a key:
* SMTP_Server_Error, in this case, the value is the
string as returned by the server (the error code should
be included too by the server in the string)
* Timeout, the value is the amount of seconds the
timeout was set to
* POE::Wheel::* depending on the wheel that returned
error on us ;-) the value is a ref to an array
containing ARG0 .. ARG3
* Configure, for AUTH misconfiguration
* MessageFile_Error for not being able to slurp the
contents of the file given to MessageFile, in case the
parameter was set.
Please note that in case the file is opened
successfully and we get an error from the ReadWrite
Wheel, then the hash key is 'POE::Wheel::ReadWrite'
ARG2 ARG2 Contains the SMTP Transaction log if
TransactionLog is enabled, in the form:
<- string received from server
-> string to be sent to server Note that it is
possible the string sent to server may not arrive there
ARG2 is undefined if TransactionLog is not enabled
ARG3 This contains a single line (scalar) describing the
error. It's useful for displaying the error in SMTP
clients using PoCo
Defaults to nothing. This means that the Component will not
trigger any event and will silently go away.
Auth ESMTP Authentication
Currently supported mechanism: PLAIN
If you are interested in implementing other mechanisms, please
send me an email, it should be piece of cake.
Hash ref with the following fields:
mechanism
The mechanism to use. Currently only PLAIN auth is
supported
user User name
pass User password
SEE ALSO
RFC2821 POE POE::Session
BUGS
· Currently the Component sends only HELO to the server, except
for when using Auth.
· PoCo doesn't keep a list of expected responses from TCP server,
which means that in case the Server is responding something
during DATA transaction, the PoCo will hapily send the message.
Please let me know if this is an issue for someone.
Bug Reporting
Please report bugs using the project's page interface, at:
<https://savannah.nongnu.org/projects/pococlsmtp/>
Unified format patches are more than welcome.
KNOWN ISSUES
Bare LF characters
Note that the SMTP protocol forbids bare LF characters in e-mail
messages. PoCoClSMTP doesn't do any checking whether you message is
SMTP compliant or not.
Most of the SMTP servers in the wild are tolerant with bare LF
characters, but you shouldn't count on that.
The point is you shouldn't send email messages having bare LF
characters. See: http://cr.yp.to/docs/smtplf.html
ESMTP error codes 1XY
ESMTP error codes 1XY are ignored and considered as 2XY codes
ACKNOWLEDGMENTS
BinGOs for ideas/patches and testing
Mike Schroeder for ideas
AUTHOR
George Nistorica, "<ultradm@cpan.org>"
COPYRIGHT & LICENSE
Copyright 2005 - 2007 George Nistorica, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.14.1 2009-09-02 POE::Component::Client::SMTP(3)
