NAME
    Mail::Delivery::SMTP - interface for SMTP service

SYNOPSIS
    To initialize,

        use Mail::Message;

          ... make $message (Mail::Message object) ...

        use Mail::Delivery::SMTP;
        my $fp  = sub { $curproc->log(@_);}; # pointer to the log function
        my $sfp = sub { my ($s) = @_; print $s; print "\n" if $s !~ /\n$/o;};
        my $service = new Mail::Delivery::SMTP {
            log_function       => $fp,
            smtp_log_function  => $sfp,
            default_io_timeout => 10,
        };
        if ($service->error) { $curproc->logerror($service->error); return;}

    To start delivery, use deliver() method in this way.

        $service->deliver(
                          {
                              smtp_servers    => '[::1]:25 127.0.0.1:25',

                              smtp_sender     => 'rudo@nuinui.net',
                              recipient_maps  => $recipient_maps,
                              recipient_limit => 1000,

                              message         => $message,
                          });

    "message" is a "Mail::Message" object. You can specify the recipient
    list as an ARRAY REFERENCE.

        # reference to an array of recipients
        @array = ( 'kenken@nuinui.net' );

        $service->deliver(
                          {
                              smtp_servers    => '[::1]:25 127.0.0.1:25',

                              smtp_sender     => 'rudo@nuinui.net',
                              recipient_array => \@array,
                              recipient_limit => 1000,

                              message         => $message,
                          });

DESCRIPTION
    This module provides SMTP/ESMTP mail delivery service. It tries IPv6
    connection If possible.

    The socket creation and tcp connection is controlled by sub-classes,
    "Mail::Delivery::Net::INET4" and "Mail::Delivery::Net::INET6".

    It sends a list of all recipients indicated by $recipient_maps.
    "IO::Adapter" resolves $recipient_maps and provides the abstract IO
    layer. It provides the usual file IO methods for each "map". See
    IO::Adapter for more details.

METHODS
  new($args)
    the constructor. Please specify it in a hash reference as an argument of
    new(). Several parameters on logging and timeout et. al. are avialable.

       hash key             value
       --------------------------------------------
       log_function         reference to function for logging
       smtp_log_function    reference to function for logging
       default_io_timeout   default timeout associated with the socket IO

    "log_function()" is the function pointer to write a message in the log
    file. "smtp_log_function()" is special function pointer to log SMTP
    transactions.

  deliver($args)
    start delivery process. You can specify the following parameter at $args
    HASH REFERENCE.

        hash key           value
        --------------------------------------------
        smtp_servers       127.0.0.1:25 [::1]:25
        smtp_sender        sender's mail address
        recipient_maps     $recipient_maps
        recipient_limit    recipients in one SMTP transactions
        header             FML::Header object
        body               Mail::Message object

    "smtp_servers" is a list of MTA's (Mail Transport Agents). The syntax of
    each MTA is "host:port" or "address:port" style. If you use a raw IPv6
    address, use "[address]:port" syntax. For example, [::1]:25 (IPv6
    loopback address). You can specify a combination of IPv4 and IPv6
    addresses at "smtp_servers". "deliver()" automatically tries smtp
    connection on both protocols.

    "smtp_sender" is the sender's email address. It is used at MAIL FROM:
    command.

    "recipient_maps" is a list of "maps". See IO::Adapter for more details.
    For example,

    To read addresses from a file, specify the map as

             file:/var/spool/ml/elena/recipients

    and to read addresses from /etc/group

             unix.group:fml

    "recipient_limit" is the max number of recipients in one SMTP
    transaction. 1000 by default, which corresponds to the limit by
    "Postfix".

    "header" is an "FML::Header" object.

    "body" is a "Mail::Message" object. See Mail::Message for more details.

SEE ALSO
    IO::Socket, Mail::Delivery::Utils, Mail::Delivery::INET4,
    Mail::Delivery::INET6, IO::Adapter

    See *http://www.postfix.org/* on "Postfix" which replaces sendmail with
    little effort but provides a lot of compatibility except for
    sendmail.cf.

CODING STYLE
    See "http://www.fml.org/software/FNF/" on fml coding style guide.

AUTHOR
    Ken'ichi Fukamachi

COPYRIGHT
    Copyright (C) 2000,2001,2002,2003,2004,2006,2012 Ken'ichi Fukamachi

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

HISTORY
    Mail::Delivery::SMTP first appeared in fml8 mailing list driver package.
    See "http://www.fml.org/" for more details.