@node Net/SMTP, Net/SNPP, Net/Ping, Module List
@unnumbered Simple Mail transfer Protocol Client


@unnumberedsec NAME

Net::SMTP - Simple Mail transfer Protocol Client

@unnumberedsec SYNOPSIS

@example
use Net::SMTP;

# Constructors
$smtp = Net::SMTP->new(@'mailhost@');
$smtp = Net::SMTP->new(@'mailhost@', Timeout => 60);
@end example

@unnumberedsec DESCRIPTION

This module implements a client interface to the SMTP protocol, enabling
a perl5 application to talk to SMTP servers. This documentation assumes
that you are familiar with the SMTP protocol described in RFC821.

A new Net::SMTP object must be created with the new method. Once
this has been done, all SMTP commands are accessed through this object.

@unnumberedsec EXAMPLES

This example prints the mail domain name of the SMTP server known as mailhost:

@example
#!/usr/local/bin/perl -w

use Net::SMTP;

$smtp = Net::SMTP->new(@'mailhost@');

print $smtp->domain,"\n";

$smtp->quit;
@end example

This example sends a small message to the postmaster at the SMTP server
known as mailhost:

@example
#!/usr/local/bin/perl -w

use Net::SMTP;

$smtp = Net::SMTP->new(@'mailhost@');

$smtp->mail($ENV@{USER@});

$smtp->to(@'postmaster@');

$smtp->data();

$smtp->datasend("To: postmaster\n");
$smtp->datasend("\n");
$smtp->datasend("A simple test message\n");

$smtp->dataend();

$smtp->quit;
@end example

@unnumberedsec CONSTRUCTOR

@table @asis
@item new ( HOST, [ OPTIONS ] )
This is the constructor for a new Net::SMTP object. @code{HOST} is the
name of the remote host to which a SMTP connection is required.

OPTIONS are passed in a hash like fasion, using key and value pairs.
Possible options are:

@strong{Hello} - SMTP requires that you identify yourself. This option
specifies a string to pass as your mail domain. If not
given a guess will be taken.

@strong{Timeout} - Maximum time, in seconds, to wait for a response from the
SMTP server (default: 120)

Debug - Enable debugging information

Example:

@example
$smtp = Net::SMTP->new(@'mailhost@',
			   Hello => @'my.mail.domain@'
			  );
@end example

@end table
@unnumberedsec METHODS

Unless otherwise stated all methods return either a @emph{true} or @emph{false}
value, with @emph{true} meaning that the operation was a success. When a method
states that it returns a value, falure will be returned as undef or an
empty list.

@table @asis
@item domain ()
Returns the domain that the remote SMTP server identified itself as during
connection.

@item hello ( DOMAIN )
Tell the remote server the mail domain which you are in using the HELO
command.

@item mail ( ADDRESS )
@itemx send ( ADDRESS )
@itemx send_or_mail ( ADDRESS )
@itemx send_and_mail ( ADDRESS )
Send the appropriate command to the server MAIL, SEND, SOML or SAML. @code{ADDRESS}
is the address of the sender. This initiates the sending of a message. The
method recipient should be called for each address that the message is to
be sent to.

@item reset ()
Reset the status of the server. This may be called after a message has been 
initiated, but before any data has been sent, to cancel the sending of the
message.

@item recipient ( ADDRESS [, ADDRESS [ ...]] )
Notify the server that the current message should be sent to all of the
addresses given. Each address is sent as a separate command to the server.
Should the sending of any address result in a failure then the
process is aborted and a @emph{false} value is returned. It is up to the
user to call reset if they so desire.

@item to ()
A synonym for recipient

@item data ( [ DATA ] )
Initiate the sending of the data fro the current message. 

@code{DATA} may be a reference to a list or a list. If specified the contents
of @code{DATA} and a termination string @code{".\r\n"} is sent to the server. And the
result will be true if the data was accepted.

If @code{DATA} is not specified then the result will indicate that the server
wishes the data to be sent. The data must then be sent using the datasend
and dataend methods defined in @code{Net::Cmd}.

@item expand ( ADDRESS )
Request the server to expand the given address Returns a reference to an array
which contains the text read from the server.

@item verify ( ADDRESS )
Verify that @code{ADDRESS} is a legitimate mailing address.

@item help ( [ $subject ] )
Request help text from the server. Returns the text or undef upon failure

@item quit ()
Send the QUIT command to the remote SMTP server and close the socket connection.

@end table
@unnumberedsec SEE ALSO

@xref{Net/Cmd,Net/Cmd},

@unnumberedsec AUTHOR

Graham Barr <Graham.Barr@@tiuk.ti.com>

@unnumberedsec REVISION

$Revision: 2.1 $
$Date: 1996/08/20 20:23:56 $

The VERSION is derived from the revision by changing each number after the
first dot into a 2 digit number so

@example
Revision 1.8   => VERSION 1.08
Revision 1.2.3 => VERSION 1.0203
@end example

@unnumberedsec COPYRIGHT

Copyright (c) 1995 Graham Barr. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.

