
=head1 NAME


Mail::Transport::SMTP - transmit messages without external program

=head1 CLASS INHERITANCE

Mail::Transport::SMTP
   is a Mail::Transport::Send
   is a Mail::Transport
   is a Mail::Reporter

=head1 SYNOPSIS


 my $sender = Mail::Transport::SMTP->new(...);
 $sender->send($message);

 $message->send(via => 'smtp');

=head1 DESCRIPTION


This module implements transport of C<Mail::Message> objects by negotiating
to the destination host directly by using the SMTP protocol, without help of
C<sendmail>, C<mail>, or other programs on the local host.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS X<new>

 OPTION               DEFAULT
 debug                <false>
 helo_domain          <from Net::Config>
 hostname             <from Net::Config>
 interval             30
 log                  'WARNINGS'
 password             undef
 port                 undef
 proxy                <from Net::Config>
 retry                <false>
 timeout              120
 trace                'WARNINGS'
 username             undef
 via                  'smtp'

=over 4

=item B<debug> =E<gt> BOOLEAN X<new(debug)>

Simulate transmission: the SMTP protocol output will be sent to your
screen.

=item B<helo_domain> =E<gt> HOST X<new(helo_domain)>

The fully qualified name of the sender's host (your system) which
is used for the greeting message to the receiver.  If not specified,
L<Net::Config> or else L<Net::Domain> are questioned to find it.
When even these do not supply a valid name, the name of the domain in the
C<From> line of the message is assumed.

=item B<hostname> =E<gt> HOSTNAME|ARRAY-OF-HOSTNAMES

See Mail::Transport::new(hostname)

=item B<interval> =E<gt> SECONDS

See Mail::Transport::new(interval)

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<password> =E<gt> STRING

See Mail::Transport::new(password)

=item B<port> =E<gt> INTEGER

See Mail::Transport::new(port)

=item B<proxy> =E<gt> PATH

See Mail::Transport::new(proxy)

=item B<retry> =E<gt> NUMBER|undef

See Mail::Transport::new(retry)

=item B<timeout> =E<gt> SECONDS X<new(timeout)>

The number of seconds to wait for a valid response from the server before
failing.

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=item B<username> =E<gt> STRING

See Mail::Transport::new(username)

=item B<via> =E<gt> CLASS|NAME

See Mail::Transport::new(via)

=back

=back

=head2 Server Connection

=over 4

=item B<findBinary> NAME [, DIRECTORIES]

See Mail::Transport::findBinary()

=item B<remoteHost> 

See Mail::Transport::remoteHost()

=item B<retry> 

See Mail::Transport::retry()

=back

=head2 Sending Mail

=over 4

=item B<contactAnyServer>  X<contactAnyServer>

Creates the connection to the SMTP server.  When more than one hostname
was specified, the first which accepts a connection is taken.  An
L<IO::Server::INET> object is returned.

=item B<putContent> MESSAGE, FILEHANDLE, OPTIONS

See Mail::Transport::Send::putContent()

=item B<send> MESSAGE, OPTIONS

See Mail::Transport::Send::send()

=item B<tryConnectTo> HOST, OPTIONS X<tryConnectTo>

Try to establish a connection to deliver SMTP to the specified HOST.  The
OPTIONS are passed to the C<new> method of L<Net::SMTP>.

=item B<trySend> MESSAGE, OPTIONS X<trySend>

Try to send the MESSAGE once.   This may fail, in which case this
method will return C<false>.  In list context, the reason for failure
can be caught: in list context C<trySend> will return a list of
five values:

 (success, error code, error text, error location, quit success)

Success and quit success are booleans.  The error code and -text are
protocol specific codes and texts.  The location tells where the
problem occurred.

 OPTION               DEFAULT
 from                 []
 to                   []

=over 4

=item B<from> =E<gt> ADDRESS X<trySend(from)>

Your own identification.  This may be fake.  If not specified, it is
taken from the C<From> field in the header.

=item B<to> =E<gt> ADDRESS|[ADDRESSES] X<trySend(to)>

Alternative destinations.  If not specified, the C<To>, C<Cc> and C<Bcc>
fields of the header are used.  An address is a string or a Mail::Address
object.

=back

=back

=head2 Logging and Tracing

=over 4

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<DESTROY> 

See Mail::Reporter::DESTROY()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>) with the help of many.

=head1 VERSION

This code is beta, version 2.019.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
