NAME
POE::Component::Client::SMTP - The great new POE::Component::Client::SMTP!
VERSION
Version 0.01
SYNOPSIS
use POE::Component::Client::SMTP;
POE::Component::Client::SMTP->send(
alias => 'smtp_client',
smtp_server => 'foo.bar.com', # default localhost
smtp_port => 25, # default 25
smtp_sender => 'foo@bar.com', # will croak if emtpy
smtp_recipient => 'foo@baz.com', # will croak if empty
to => "Foo Baz", # defaults to smtp_recipient
from => "Foo Bar", # defaults to smtp_sender
cc => ['a@foo.bar', 'b@foo.bar'], # not implemented yet
bcc => ['bcc1@bar.foo', 'bcc2@bar.foo'], # not implemented yet
subject => "Hi Foo!" # defaults to "(none)"
smtp_data => $ref_to_data,
smtp_timeout => 30, # seconds, defaults to 30
debug => 1, # defaults to 0
SMTPSendSuccessEvent => $success_event,
SMTPSendFailureEvent => $failure_event,
);ABSTRACT
POE::Component::Client::SMTP can be used to send asynchronous e-mail messages while your POE program still does something else in the meantime.
Currently it doesn't support ESMTP features like sending mails trough an encrypted connection, honouring SMTP authentification or fancy stuff like this. It just sends electronic messages trough a SMTP daemon.
METHODS
send
This method handles everything needed to send an email message (SMTP compliant, not ESMTP aware).
Arguments
- alias
-
The component's alias
- smtp_server
-
SMTP server address; defaults to localhost
- smtp_port
-
SMTP server port; defaults to 25
- smtp_sender
-
Email address from where the message originates; mandatory
- smtp_recipient
-
Email address for the message delivery; mandatory
- to
-
Recipient's name as it appears in the message's "To:" field; defaults to smtp_recipient
- from
-
Sender's name as it appears in the message's "From:" field; defaults to smtp_sender
- cc
-
Not implemented yet;
- bcc
-
Not implemented yet;
- subject
-
The subject of the message
- smtp_data
-
The body of the message
- SMTPSendSuccessEvent
-
Specify what event is to be sent back upon successful mail delivery
- SMTPSendFailureEvent
-
Specify what event is to be sent back upon failure of mail delivery
- smtp_timeout
-
Timeout to SMTP connection; defaults to 30 seconds (not implemented yet)
- debug
-
Run in debug mode
Events
PoCo::Client::SMTP sends two events: SMTPSendFailureEvent and SMTPSendFailureEvent.
- SMTPSendSuccessEvent
-
SMTPSendSuccessEvent is sent back to the session that spawned PoCo::Client::SMTP when the message is accepted by the SMTP server
- SMTPSendFailureEvent
-
SMTPSendFailureEvent is sent back to the session that spawned PoCo::Client::SMTP when the message has not been delivered.
There are three main reasons for failure:
1) A connection could not be established in which case this event is sent along with three parameters (as received from: POE::Wheel::SocketFactory)
2) An error occured while network connection still active with the SMTP server in which case this event is sent along with three parameters (as received from POE::Wheel::ReadWrite)
3) An error occured while talking with the SMTP daemon; this means that a misunderstanding between PoCo::Client::SMTP and the SMTP server has occured; if you feel this shouldn't have happened, fill a bug report along with the session log.
If running in debug mode, you will receive not only the last line received from the server, but the entire SMTP session log.
Note
Note that SMTPSendSuccessEvent and SMTPSendFailureEvent are relative to what the SMTP server tells us; even if the SMTP server accepts the message for delivery, this is not a guarantee that the message actually gets delivered.
EXAMPLE
...
POE::Session->create(
...
SMTP_Send_Success_Event => \&smtp_success,
SMTP_Send_Failure_Event => \&smtp_failure,
...
);
...
$data = "Here is the info I want to send you:";
$data .= "1 2 3 4 5 6";
...
POE::Component::Client::SMTP->send(
alias => 'smtp_client',
smtp_server => 'mail-host.foo.bar',
smtp_port => 25,
smtp_sender => 'me@foo.bar',
smtp_recipient => 'my_girlfriend@baz.com',
from => "My Name Here",
to => "The Girls's Name",
subject => "I've just did your homework",
smtp_data => \$data,
SMTPSendSuccessEvent => 'SMTP_Send_Success_Event',
SMTPSendFailureEvent => 'SMTP_Send_Failure_Event',
);
...
sub smtp_success{
Logger->log("MAIL sent successfully ");
# do something useful here ...
}
sub smtp_failure{
# Oops
Logger->log("MAIL sending failed");
my ($er, $er1, $er2) = @_[ARG0 .. ARG3];
if (!defined ($er1) ){
Logger->log("Error during SMTP talk");
}else{
Logger->log("Error ducing SMTP connecton");
}
} BUGS
* Beware that the interface can be changed in the future!
* Currently there is no timeout checking for established connections; so the PoCo::Client::SMTP may hang if it doesn't receive proper response from the SMTP::Server
Please report any bugs or feature requests to bug-poe-component-client-smtp@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-Client-SMTP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
CAVEATS
Values given to send() are minimally checked.
ACKNOWLEDGEMENTS
TODO
* piping support thru sendmail binary
* add support for ESTMP (maybe a derivate class? like: POE::Component::Client::SMTP::Extended)
* add timeout for network operations
* freeze the interface
SEE ALSO
POE::Kernel, POE::Session, POE::Component, POE::Wheel::SocketFactory, POE::Wheel::ReadWrite
AUTHOR
George Nistorica, <george@nistorica.ro>
COPYRIGHT & LICENSE
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.