POE::Component::Client::SMTP - Asynchronous mail sending with POE
Version 0.12
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.
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 ;-)
As you may have noticed, the API has changed, and this module version is not backward compatible.
So if you are upgrading from a previous version, please adjust your code.
Below are the methods this Component has:
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.
There are two kinds of parameters PoCoClient::SMTP supports: Email related parameters and POE related parameters:
This holds the sender's email address
Defaults to 'root@localhost', just don't ask why.
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.
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 ;-)))
Defaults to an empty mail body.
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'
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
Set the timeout for SMTP transactions (seconds).
Defaults to 30 seconds
Hostname to present when sending EHLO/HELO command.
Defaults to "localhost"
This attribute is set when creating the socket connection to the SMTP server. See POE::Wheel::SocketFactory for details.
Set the debugging level. A value greater than 0 increases the Component's verbosity
Defaults to 0
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.
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.
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.
It will send you the Context as ARG0 if Context is defined.
Event you want to be called by PoCoClient::SMTP in case of failure.
You will get back the following information:
The Context you've set when spawning the component, or undef if no Context specified
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 an array containing ARG0 .. ARG3
RFC2821 POE POE::Session
Currently the Component sends only HELO to the server, not EHLO. This shouldn't be such a problem as for the moment the Component hasn't any ESMTP features.
Please report bugs using the project's page interface, at: https://savannah.nongnu.org/projects/pococlsmtp/
Unified format patches are more than welcome.
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
George Nistorica, <ultradm@cpan.org>
<ultradm@cpan.org>
Copyright 2005 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.
To install POE::Component::Client::SMTP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::Client::SMTP
CPAN shell
perl -MCPAN -e shell install POE::Component::Client::SMTP
For more information on module installation, please visit the detailed CPAN module installation guide.