NAME
    Mail::Sendmail v. 0.74 - Simple platform independent mailer

SYNOPSIS
      use Mail::Sendmail;

      %mail = ( To      => 'you@there.com',
                From    => 'me@here.com',
                Message => "This is a minimalistic message"
               );

      if (sendmail %mail) { print "Mail sent OK.\n" }
      else { print "Error sending mail: $Mail::Sendmail::error \n" }

      print "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;

DESCRIPTION
    Simple platform independent e-mail from your perl script.

    After struggling for some time with various command-line mailing
    programs which never did exactly what I wanted, I put together
    this Perl only solution.

    Mail::Sendmail contains mainly &sendmail, which takes a hash
    with the message to send and sends it...

INSTALLATION
    Standard:

        perl Makefile.PL
        make
        make test
        make install

    or manual:

        Copy Sendmail.pm to Mail/ in your Perl lib directory.
          (eg. c:\Perl\lib\Mail\, c:\Perl\lib\site\Mail\,
           /usr/lib/perl5/site_perl/Mail/, ...
           or whatever it is on your system)

    At the top of Sendmail.pm, set your default SMTP server, unless
    you specify it with each message, or want to use the default.

    See the the NOTES manpage section about MIME::QuotedPrint. It is
    not required but strongly recommended.

FEATURES
        Internal Bcc: and Cc: support (even on broken servers)

        Allows real names in From: and To: fields

        Doesn't send unwanted headers, and allows you to send any
        header(s) you want

        Adds the Date header if you don't supply your own

        Automatic Time Zone detection

LIMITATIONS
    Doesn't send attachments, unless you provide the appropriate
    headers and boundaries yourself, but that may not be practical,
    and I haven't tested it.

    The SMTP server has to be set manually in Sendmail.pm or in your
    script, unless you can live with the default (Compuserve's
    smpt.site1.csi.com).

CONFIGURATION
    default SMTP server
        Set this at the top of Sendmail.pm, unless you want to use
        the provided default.

        You can override the default for a particular message by
        adding it to your %message hash with a key of 'Smtp':

        `$message{Smtp} = 'newserver.my-domain.com';'

        Overriding it globally in your script with:

        `$Mail::Sendmail::default_smtp_server = 'newserver.my-
        domain.com';'

        also works, but this may change in future versions! Better
        do it in Sendmail.pm or in the %message hash.

    other configuration settings
        See individual entries under DETAILS below.

DETAILS
    sendmail()
        sendmail is the only thing exported to your namespace by
        default

        `sendmail(%mail) || print "Error sending mail:
        $Mail::Sendmail::error\n";'

        It takes a hash containing the full message, with keys for
        all headers, Body,and optionally for another non-default
        SMTP server and/or Port. It returns 1 on success or 0 on
        error, and rewrites `$Mail::Sendmail::error' and
        `$Mail::Sendmail::log'.

        Keys are NOT case-sensitive.

        The colon after headers is not necessary.

        The Body part key can be called "Body", "Message" or "Text".
        The smtp server key can be called "Smtp" or "Server".

        The following headers are added unless you specify them
        yourself:

            Mime-version: 1.0
            Content-type: 'text/plain; charset="iso-8859-1"'

            Content-transfer-encoding: quoted-printable
            or (if MIME::QuotedPrint not installed)
            Content-transfer-encoding: 8bit

            Date: [string returned by time_to_date()]

        If you put an 'X-mailer' header, the package version number
        is appended to it.

    The following are not exported by default, but you can still
    access them with their full name, or request their export on the
    use line like in: `use Mail::Sendmail qw($address_rx
    time_to_date);'

    Mail::Sendmail::time_to_date()
        convert time ( as from `time()' ) to an RFC 822 compliant
        string for the Date header. See also $Mail::Sendmail::TZ.

    $Mail::Sendmail::error
        When you don't run with the -w flag, the module sends no
        errors to STDERR, but puts anything it has to complain about
        in here. You should probably always check if it says
        something.

    $Mail::Sendmail::log
        A summary that you could write to a log file after each send

    $Mail::Sendmail::address_rx
        A handy regex to recognize e-mail addresses.

          Example:
            $rx = $Mail::Sendmail::address_rx;
            if (/$rx/) {
              $address=$1;
              $user=$2;
              $domain=$3;
            }

        The regex is a compromise between RFC 822 spec. and a simple
        regex. See the code and comments if interested, and let me
        know if it doesn't recognize what you expect.

    $Mail::Sendmail::default_smtp_server
        see Configuration above.

    $Mail::Sendmail::default_smtp_port
        If your server doesn't use the default port 25, change this
        at the top of Sendmail.pm, or override it for a particular
        message by adding it to your %message hash with a key of
        'Port':

        `$message{Port} = 8025;'

        Global overriding with `$Mail::Sendmail::default_smtp_port =
        8025;' is deprecated as above for the server, since future
        versions may not use this anymore.

    $Mail::Sendmail::default_sender
        You can set this in Sendmail.pm, so you don't need to define
        %message{From} in every message.

    $Mail::Sendmail::TZ
        Your time zone. It is set automatically, from the difference
        between time() and gmtime(), unless you have preset it in
        Sendmail.pm.

        Or you can force it from your script, using an RFC 822
        compliant format:

        `$Mail::Sendmail::TZ = "+0200"; # Western Europe in summer'

    $Mail::Sendmail::use_MIME
        This is set to 1 if you have MIME::QuotedPrint, to 0
        otherwise. It's available in case you want to force it to
        zero and do the encoding yourself. You would want this to do
        multipart messages and/or attachments, but you may prefer
        using some other package if you have complex needs.

    $Mail::Sendmail::connect_retries
        Number of retries when the connection to the server fails.
        Default is 1 retry (= 2 connection attempts).

    $Mail::Sendmail::retry_delay
        Seconds to wait before retrying to connect to the server.
        Default is a low 5 seconds, so if you output results to a
        web page, you don't time out. Set it much higher for scripts
        that don't mind waiting.

    $Mail::Sendmail::VERSION
        The package version number (this cannot be exported)

ANOTHER EXAMPLE
      use Mail::Sendmail;

      print STDERR "Testing Mail::Sendmail version $Mail::Sendmail::VERSION\n";
      print STDERR "smtp server: $Mail::Sendmail::default_smtp_server\n";
      print STDERR "server port: $Mail::Sendmail::default_smtp_port\n";

      %mail = (
          #To      => 'No to field this time, only Bcc and Cc',
          #From    => 'not needed, use default',
          Bcc     => 'Someone <him@there.com>, Someone else her@there.com',
          # only addresses are extracted from Bcc, real names disregarded
          Cc      => 'Yet someone else <xz@whatever.com>',
          # Cc will appear in the header. (Bcc will not)
          Subject => 'Test message',
          'X-Mailer' => "Mail::Sendmail",
      );

      $mail{Smtp} = 'special_server.for-this-message-only.domain.com';
      $mail{'X-custom'} = 'My custom additionnal header';
      $mail{'mESSaGE : '} = "The message key looks terrible, but works.";
      # cheat on the date:
      $mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 ),

      if (sendmail %mail) { print "Mail sent OK.\n" }
      else { print "Error sending mail: $Mail::Sendmail::error \n" }

      print STDERR "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;

CHANGES
    Many changes and bug-fixes since version 0.73. See Changes file.

AUTHOR
    Milivoj Ivkovic mi@alma.ch or ivkovic@csi.com

NOTES
    MIME::QuotedPrint is used by default on every message if
    available. It is needed to send accented characters reliably.
    (It is in the MIME-Base64 package at
    http://www.perl.com/CPAN/modules/by-module/MIME/ ).

    When using this module in CGI scripts, look out for problems
    related to messages sent to STDERR. Some servers don't like it,
    or log them somewhere where you don't know, or compile-time
    errors are sent before you printed the HTML headers. Either be
    sure to not run with the -w flag, or (better) print the HTML
    headers in a BEGIN{} block, and maybe redirect STDERR to STDOUT.

    This module was first based on a script by Christian Mallwitz.

    You can use it freely. (someone complained this is too vague.
    So, more precisely: do whatever you want with it, but if it's
    bad - like using it for spam or claiming you wrote it alone, or
    ...? - terrible things will happen to you!)

    I would appreciate a short (or long) e-mail note if you use this
    (and even if you don't, especially if you care to say why). And
    of course, bug-reports and/or suggestions are welcome.

    Last revision: 01.08.98. Latest version should be available at
    http://alma.ch/perl/mail.htm , and a few days later on CPAN.