/ 
Mail-Sendmail-0.73
River stage two • 20 direct dependents • 56 total dependents
/ Mail::Sendmail

NAME

Mail::Sendmail v. 0.73 - 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 STDERR "\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

- 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

- MIME::QuotedPrint is strongly recommended. It's in the MIME-Base64 package. Get it from http://www.perl.com/CPAN/modules/by-module/MIME. It is used by default on every message, and is needed to send accented characters safely.

FEATURES

- Automatic Mime quoted printable encoding (if MIME::QuotedPrint installed)

- Bcc: and Cc: support

- Doesn't send unwanted headers

- Allows you to send any header you want

- Doesn't abort sending if there is a bad recipient address among other good ones

- Returns verbose error messages

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

- Automatic Time Zone detection (hopefully)

LIMITATIONS

Doesn't send attachments. You can probably still send them if you provide the appropriate headers and boundaries, but that may not be practical, and I haven't tested it.

Not tested in a situation where the server goes down during session

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).

I couldn't test the automatic time zone detection much. If it doesn't work, set it manually (see below) and please let me know.

DETAILS

sendmail()

sendmail is the only thing exported to your namespace

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

- takes a hash containing the full message, with keys for all headers, Body, and optionally for another non-default SMTP server and/or Port. (The Body part can be called "Body", "Message" or "Text")

- returns 1 on success, 0 on error.

updates $Mail::Sendmail::error and $Mail::Sendmail::log.

Keys are not case-sensitive. They get normalized before use with ucfirst( lc $key ). The colon after headers is not necessary.

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, but you can still access them with their full name:

Mail::Sendmail::time_to_date()

convert time ( as from time() ) to a string suitable for the Date header as per RFC 822. See also $Mail::Sendmail::TZ.

$Mail::Sendmail::VERSION

The package version number

$Mail::Sendmail::error

Fatal or non-fatal socket or SMTP server errors

$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;
  }
$Mail::Sendmail::default_smtp_server

see Configuration below

$Mail::Sendmail::default_smtp_port

see Configuration below

$Mail::Sendmail::default_sender

see Configuration below

$Mail::Sendmail::TZ

Your time zone. It should be set automatically, from the difference between time() and gmtime(), unless it has been preset in Sendmail.pm.

If it doesn't work for you, let me know so I can try to fix it, and in the meantime, set it manually in RFC 822 compliant format:

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

CONFIGURATION

default SMTP server (recommended setting)

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

You can override the default in a particular script with:

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

or just for a particular message by adding it to your %message hash with a key of 'Smtp':

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

default port (optional)

If your server doesn't use the default port 25, also change this at the top of Sendmail.pm.

Or override it for a particular script with:

$Mail::Sendmail::default_smtp_port = 8025;

or just for a particular message by adding it to your %message hash with a key of 'Port':

$message{Port} = 8025;

$default_sender (optional)

If you set this, you don't need to define %message{From} in every message.

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::Sendmail::default_sender = 'This is me <myself@here.com>';

%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} = "Only a short message";
$mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 ), # cheat on the date

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

0.73: Line endings changed again to hopefully be Mac compatible at last. Automatic time zone detection. Support for SMTP Port change for single messages. Always default to quoted-printable encoding if possible. Added $Mail::Sendmail::default_sender.

0.72: Fixed line endings in Body to "\r\n". MIME quoted printable encoding is now automatic if needed. Test script can now run unattended.

0.71: Fixed Time Zone bug with AS port. Added half-hour Time Zone support. Repackaged with \n line endings instead of \r\n.

AUTHOR

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

NOTES

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

You can use it freely.

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

This version has been tested on Win95 and WinNT 4.0 with Perl 5.003_07 (AS 313) and Perl 5.004_02 (GS), and on Linux 2.0.34 (Red Hat 5.1) with 5.004_04.

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