• NAME
• SYNOPSIS
• DESCRIPTION
• INSTALLATION
• FEATURES
• LIMITATIONS
• CONFIGURATION
• DETAILS
• ANOTHER EXAMPLE
• CHANGES
• AUTHOR
• NOTES

NAME

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

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

    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 NOTES section about MIME::QuotedPrint. It is not required but strongly recommended.

FEATURES

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

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.

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

AUTHOR

NOTES

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.