.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POE::Component::Client::SMTP 3"
.TH POE::Component::Client::SMTP 3 "2008-01-07" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
POE::Component::Client::SMTP \- Asynchronous mail sending with POE
.SH "VERSION"
.IX Header "VERSION"
Version 0.17
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
PoCoClient::SMTP allows you to send email messages in an asynchronous manner,
using \s-1POE\s0.
.PP
Thus your program isn't blocking while busy talking with an (E)SMTP server.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBWarning!\fR The following examples are \fBnot\fR complete programs, and
aren't designed to be run as full blown applications. Their purpose is to
quickly
introduce you to the module.
.PP
For complete examples, check the 'eg' directory that can be found in the
distribution's kit.
.PP
A simple example:
.PP
.Vb 11
\& # 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 ;-)
.Ve
.PP
A more complex example:
.PP
.Vb 21
\& # 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    =>  \e$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 ;-)
.Ve
.SH "METHODS"
.IX Header "METHODS"
Below are the methods this Component has:
.Sh "send"
.IX Subsection "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 \fIspawn\fR method that will keep
the Session around forever, until received a 'shutdown' like event.
.PP
\fI\s-1PARAMETERS\s0\fR
.IX Subsection "PARAMETERS"
.PP
There are two kinds of parameters PoCoClient::SMTP supports: Email related
parameters and \s-1POE\s0 related parameters:
.IP "From" 8
.IX Item "From"
This holds the sender's email address
.Sp
\&\fBDefaults\fR to 'root@localhost', just don't ask why.
.IP "To" 8
.IX Item "To"
This holds a list of recipients. Note that To/CC/BCC fields are separated in
your email body. From the \s-1SMTP\s0 server's point of view (and from this
component's too) there is no difference as who is To, who \s-1CC\s0 and who \s-1BCC\s0.
.Sp
The bottom line is: be careful how you construct your email message.
.Sp
\&\fBDefaults\fR to root@localhost', just don't ask why.
.IP "Body" 8
.IX Item "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 ;\-)))
.Sp
\&\fBNote\fR that \fIMessageFile\fR and \fIFileHandle\fR take precedense over \fIBody\fR.
.Sp
In case \fIMessageFile\fR or \fIFileHandle\fR are set, \fIBody\fR is discarded.
.Sp
\&\fBDefaults\fR to an empty mail body.
.IP "Server" 8
.IX Item "Server"
Here you specify the relay \s-1SMTP\s0 server to be used by this component. Currently
piping thru sendmail is not supported so you need a \s-1SMTP\s0 server to actually
do the mail delivery (either by storing the mail somewhere on the hard
drive, or by relaying to another \s-1SMTP\s0 server).
.Sp
\&\fBDefaults\fR to 'localhost'
.IP "Port" 8
.IX Item "Port"
Usually \s-1SMTP\s0 servers bind to port 25. (See /etc/services if you are using a
*NIX like O.S.).
.Sp
Sometimes, \s-1SMTP\s0 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.
.Sp
\&\fBDefaults\fR to 25
.IP "Timeout" 8
.IX Item "Timeout"
Set the timeout for \s-1SMTP\s0 transactions (seconds).
.Sp
\&\fBDefaults\fR to 30 seconds
.IP "MyHostname" 8
.IX Item "MyHostname"
Hostname to present when sending \s-1EHLO/HELO\s0 command.
.Sp
\&\fBDefaults\fR to \*(L"localhost\*(R"
.IP "BindAddress" 8
.IX Item "BindAddress"
This attribute is set when creating the socket connection to the \s-1SMTP\s0 server.
See POE::Wheel::SocketFactory for details.
.IP "BindPort" 8
.IX Item "BindPort"
This attribute is set when creating the socket connection to the \s-1SMTP\s0 server.
See POE::Wheel::SocketFactory for details.
.IP "Debug" 8
.IX Item "Debug"
Set the debugging level. A value greater than 0 increases the Component's
verbosity
.Sp
\&\fBDefaults\fR to 0
.IP "Alias" 8
.IX Item "Alias"
In case you have multiple PoCoClient::SMTP Sessions, you'd like to handle them
separately, so use Alias to differentiate them.
.Sp
This holds the Session's alias.
.Sp
\&\fBDefaults\fR to nothing. Internally it refcounts to stay alive.
.IP "Context" 8
.IX Item "Context"
You may want to set a context for your POE::Component::Client::SMTP session.
This is a scalar.
.Sp
When the caller session receives SMTP_Success or SMTP_Failure event, the
context is also passed to it if defined.
.IP "MessageFile" 8
.IX Item "MessageFile"
Specify a file name from where the email body is slurped.
.Sp
\&\fBNote:\fR that you still need to specify the parameters like From, To etc.
.IP "FileHandle" 8
.IX Item "FileHandle"
Specify a filehandle from where the email body is slurped.
.Sp
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.
.Sp
\&\fBIt is important that the handle is readable\fR so please check that before using it.
.Sp
\&\fBNote:\fR that you still need to specify the parameters like From, To etc.
.IP "TransactionLog" 8
.IX Item "TransactionLog"
In case you want to get back the Log between the client and the server, you
need to enable this.
.Sp
\&\fBDefaults\fR to disabled.
.IP "SMTP_Success" 8
.IX Item "SMTP_Success"
Event you want to be called by PoCoClient::SMTP in case of success.
.Sp
\&\fBDefaults\fR to nothing. This means that the Component will not trigger any
event and will silently go away.
.RS 8
.IP "\s-1ARG0\s0" 8
.IX Item "ARG0"
Contains Context if any
.IP "\s-1ARG1\s0" 8
.IX Item "ARG1"
\&\s-1ARG1\s0 Contains the \s-1SMTP\s0 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
.Sp
\&\s-1ARG1\s0 is undefined if TransactionLog is not enabled
.RE
.RS 8
.RE
.IP "SMTP_Failure" 8
.IX Item "SMTP_Failure"
Event you want to be called by PoCoClient::SMTP in case of failure.
.Sp
You will get back the following information:
.RS 8
.IP "\s-1ARG0\s0" 8
.IX Item "ARG0"
The Context you've set when spawning the component, or undef if no Context
specified
.IP "\s-1ARG1\s0" 8
.IX Item "ARG1"
A hash ref that currently has only a key:
.Sp
* 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)
.Sp
* Timeout, the value is the amount of seconds the timeout was set to
.Sp
* POE::Wheel::* depending on the wheel that returned error on us ;\-)
the value is a ref to an array containing \s-1ARG0\s0 .. \s-1ARG3\s0
.Sp
* Configure, for \s-1AUTH\s0 misconfiguration
.Sp
* MessageFile_Error for not being able to slurp the contents of the file given
to MessageFile, in case the parameter was set.
.Sp
Please \fBnote\fR 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'
.IP "\s-1ARG2\s0" 8
.IX Item "ARG2"
\&\s-1ARG2\s0 Contains the \s-1SMTP\s0 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
.Sp
\&\s-1ARG2\s0 is undefined if TransactionLog is not enabled
.RE
.RS 8
.Sp
\&\fBDefaults\fR to nothing. This means that the Component will not trigger any
event and will silently go away.
.RE
.IP "Auth" 8
.IX Item "Auth"
\&\s-1ESMTP\s0 Authentication
.Sp
Currently supported mechanism: \s-1PLAIN\s0
.Sp
If you are interested in implementing other mechanisms, please send me an email, it should be piece of cake.
.Sp
Hash ref with the following fields:
.RS 8
.IP "mechanism" 8
.IX Item "mechanism"
The mechanism to use. Currently only \s-1PLAIN\s0 auth is supported
.IP "user" 8
.IX Item "user"
User name
.IP "pass" 8
.IX Item "pass"
User password
.RE
.RS 8
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1RFC2821\s0 \s-1POE\s0 POE::Session
.SH "BUGS"
.IX Header "BUGS"
.IP "* Currently the Component sends only \s-1HELO\s0 to the server, except for when using Auth." 8
.IX Item "Currently the Component sends only HELO to the server, except for when using Auth."
.Sh "Bug Reporting"
.IX Subsection "Bug Reporting"
Please report bugs using the project's page interface, at:
<https://savannah.nongnu.org/projects/pococlsmtp/>
.PP
Unified format patches are more than welcome.
.SH "KNOWN ISSUES"
.IX Header "KNOWN ISSUES"
.Sh "Bare \s-1LF\s0 characters"
.IX Subsection "Bare LF characters"
Note that the \s-1SMTP\s0 protocol forbids bare \s-1LF\s0 characters in e\-mail messages.
PoCoClSMTP doesn't do any checking whether you message is \s-1SMTP\s0 compliant or not.
.PP
Most of the \s-1SMTP\s0 servers in the wild are tolerant with bare \s-1LF\s0 characters, but
you shouldn't count on that.
.PP
The point is you shouldn't send email messages having bare \s-1LF\s0 characters.
See: http://cr.yp.to/docs/smtplf.html
.SH "ESMTP error codes 1XY"
.IX Header "ESMTP error codes 1XY"
\&\s-1ESMTP\s0 error codes 1XY are ignored and considered as 2XY codes
.SH "ACKNOWLEDGMENTS"
.IX Header "ACKNOWLEDGMENTS"
.IP "BinGOs for ideas/patches and testing" 4
.IX Item "BinGOs for ideas/patches and testing"
.PD 0
.IP "Mike Schroeder for ideas" 4
.IX Item "Mike Schroeder for ideas"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
George Nistorica, \f(CW\*(C`<ultradm@cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2005 \- 2007 George Nistorica, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.