NAME
POE::Component::Client::SMTP - Sending emails using POE
VERSION
Version 0.02
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,
);DESCRIPTION
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; This option is mandatory
- smtp_recipient
-
Email address for the message delivery; This option is 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; must be a ref to a scalar or an array.
- 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
- 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
2) An error occured while network connection still active with the SMTP server
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 y ou feel this shouldn't have happened, fill a bug report along with the session log.
The SMTPSendFailureEvent handler receives the following parameters:
If ARG0 has a value of 1, then the error occured because of a SMTP session failure
In this case, ARG1 contains the SMTP numeric code, ARG2 contains a string message giving a short explanation of the error.
If ARG0 has a value of 2, then the error occured because of a network failure
In this case, ARG1, ARG2, and ARG3 have the values as returned by POE::Wheel::SocketFactory
If ARG0 has a value of 3, then the error occured because of a network failure
In this case, ARG1, ARG2, and ARG3 have the values as returned by POE::Wheel::ReadWrite
If ARG0 has a value of 4, then the error occured because a timeout
In this case, ARG1 holds the SMTP state the PoCoCl::SMTP is while timeouting
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 fo r delivery, it is not guaranteed that the message actually gets delivered. In case an error occurs after the SMTP server accepted the message, an error message will be sent back to the sender.
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
my $err_type = @_[ARG0];
if ( $err_type eq == 1 ){
my $error_code = @_[ARG1];
my $error_message = @_[ARG2];
Logger->log( "Received: [$err_code] $error_message from the server" );
}elsif ( $err_type == 2 ) {
...
}
} BUGS
* Beware that the interface can be changed in the future!
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.
The module assumes that the given smtp_server is a relay or the target server. This doesn't conform to the RFC 2821.
ACKNOWLEDGEMENTS
TODO
See the TODO file in the distribution.
SEE ALSO
POE::Kernel, POE::Session, POE::Component, POE::Wheel::SocketFactory, POE::Wheel::ReadWrite
RFC 2821
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.