sendmail(3)

NAME

Mail::Sendmail v. 0.78 - Simple platform independent
mailer

SYNOPSIS

use Mail::Sendmail;
%mail = ( To      => 'you@there.com',
          From    => 'me@here.com',
          Message => "This is a very short message"
         );
sendmail(%mail) or die $Mail::Sendmail::error;
print "OK. Log says:0, $Mail::Sendmail::log;

DESCRIPTION

Simple platform independent e-mail from your perl script.
Only requires Perl 5 and a network connection.

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. It is intended
to be very easy to setup and use.

INSTALLATION

Best

perl -MCPAN -e "install Mail::Sendmail"

Traditional

perl Makefile.PL
make
make test
make install

Manual

Copy Sendmail.pm to Mail/ in your Perl lib directory.

(eg. c:Perlil c:Perleil

/usr/lib/perl5/site_perl/Mail/, ... or whatever

it
is on your system)

ActivePerl's PPM

ppm install --location=http://alma.ch/perl/ppm MailSendmail

But this way you don't get a chance to have a look at
other files (Changes, Todo, test.pl, ...) and PPM
doesn't run the test script (test.pl).

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

Install MIME::QuotedPrint. This is not required but
strongly recommended.

FEATURES

Automatic time zone detection, Date: header, MIME quotedprintable encoding (if MIME::QuotedPrint installed), all
of which can be overridden.

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

Configurable retries and use of alternate servers if your
mail server is down

Good plain text error reporting

LIMITATIONS

Doesn't work on OpenVMS.

Headers are not encoded, even if they have accented char
acters.

Since the whole message is in memory (twice!), it's not
suitable for sending very big attached files.

The SMTP server has to be set manually in Sendmail.pm or
in your script, unless you have a mail server on local
host.

CONFIGURATION

Default SMTP server(s)

This is probably all you want to configure. It is usu
ally done through $mailcfg{smtp}, which you can edit at the top of the Sendmail.pm file. This is a refer
ence to a list of SMTP servers. You can also set it
from your script:

"unshift @{$Mail::Sendmail::mailcfg{'smtp'}} ,
'my.mail.server';"

Alternatively, you can specify the server in the %mail
hash you send from your script, which will do the same
thing:

"$mail{smtp} = 'my.mail.server';"

A future version will try to set useful defaults for
you during the Makefile.PL.

Other configuration settings

See %mailcfg under "DETAILS" below for other configu ration options.

DETAILS

sendmail()

sendmail is the only thing exported to your namespace by
default

"sendmail(%mail) || print "Error sending mail:
$Mail::Sendmail::error0;"

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()]

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::Send
mail::mailcfg".

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

A correct regex for valid e-mail addresses was written by
one of the judges in the obfuscated Perl contest... :-) It
is quite big. This one is an attempt to a reasonable com
promise, and should accept all real-world internet style
addresses. The domain part is required and comments or
characters that would need to be quoted are not supported.

Example:

$rx = $Mail::Sendmail::address_rx;
if (/$rx/) {

$address=$1;
$user=$2;
$domain=$3;

}

%Mail::Sendmail::mailcfg

This hash contains all configuration options. You normally
edit it once (if ever) in Sendmail.pm and forget about it,
but you could also access it from your scripts. For read
ability, I'll assume you have imported it.

The keys are not case-sensitive: they are all converted to
lowercase before use. Writing "$mailcfg{Port} = 2525;" is
OK: the default $mailcfg{port} (25) will be deleted and
replaced with your new value of 2525.

$mailcfg{smtp}

"$mailcfg{smtp} = [qw(localhost
my.other.mail.server)];"

This is a reference to a list of smtp servers, so if
your main server is down, the module tries the next
one. If one of your servers uses a special port, add
it to the server name with a colon in front, to over
ride the default port (like in my.spe
cial.server:2525).

Default: localhost. (the previous version also had
smtp.site1.csi.com which was an open relay, but it
isn't anymore)

$mailcfg{from}

"$mailcfg{from} = 'Mailing script me@mydomain.com';"

From address used if you don't supply one in your
script. Should not be of type 'user@localhost' since
that may not be valid on the recipient's host.

Default: undefined.

$mailcfg{mime}

"$mailcfg{mime} = 1;"

Set this to 0 if you don't want any automatic MIME
encoding. You normally don't need this, the module
should 'Do the right thing' anyway.

Default: 1;

$mailcfg{retries}

"$mailcfg{retries} = 1;"

How many times should the connection to the same SMTP
server be retried in case of a failure.

Default: 1;

$mailcfg{delay}

"$mailcfg{delay} = 1;"

Number of seconds to wait between retries. This delay
also happens before trying the next server in the
list, if the retries for the current server have been
exhausted. For CGI scripts, you want few retries and
short delays to return with a results page before the
http connection times out. For unattended scripts, you
may want to use many retries and long delays to have a
good chance of your mail being sent even with tempo
rary failures on your network.

Default: 1 (second);

$mailcfg{tz}

"$mailcfg{tz} = '+0800';"

Normally, your time zone is set automatically, from
the difference between "time()" and "gmtime()". This
allows you to override automatic detection in cases
where your system is confused (such as some Win32 sys
tems in zones which do not use daylight savings time:
see Microsoft KB article Q148681)

Default: undefined (automatic detection at run-time).

$mailcfg{port}

"$mailcfg{port} = 25;"

Port used when none is specified in the server name.

Default: 25.

$mailcfg{debug}

"$mailcfg{debug} =" 0;>

Prints stuff to STDERR. Not used much, and what is
printed may change without notice. Don't count on it.

Default: 0;

$Mail::Sendmail::VERSION

The package version number (you can not import this one)

Configuration variables from previous versions

The following global variables were used in version 0.74
for configuration. They should still work, but will not
in a future version (unless you complain loudly). Please
use %mailcfg if you need to access the configuration from your scripts.

$Mail::Sendmail::default_smtp_server
$Mail::Sendmail::default_smtp_port
$Mail::Sendmail::default_sender
$Mail::Sendmail::TZ
$Mail::Sendmail::connect_retries
$Mail::Sendmail::retry_delay
$Mail::Sendmail::use_MIME

This one couldn't really be used in the previous ver
sion, so I just dropped it. It is replaced by $mail_
cfg{mime} which works.

ANOTHER EXAMPLE

use Mail::Sendmail;

print "Testing Mail::Sendmail version $Mail::Send

mail::VERSION0;
print "Default server: $Mail::Sendmail::mail

cfg{smtp}->[0]0;
print "Default sender: $Mail::Sendmail::mailcfg{from}0;

%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 version $Mail::Send

mail::VERSION",

);

$mail{Smtp} = 'special_server.for-this-message-only.do

main.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.0 }
else { print "Error sending mail: $Mail::Sendmail::error

0 }

print "0il::Sendmail::log says:0, $Mail::Sendmail::log;

CHANGES

Single-letter host names bug fixed since version 0.77. See
the Changes file for the full history.

AUTHOR

Milivoj Ivkovic mi@alma.ch or ivkovic@bluewin.ch

NOTES

MIME::QuotedPrint is used by default on every message if
available. It allows reliable sending of accented charac
ters, and also takes care of too long lines (which can
happen in HTML mails). It is available in the MIME-Base64
package at http://www.perl.com/CPAN/modules/by-mod
ule/MIME/ or through PPM.

Look at http://alma.ch/perl/Mail-Sendmail-FAQ.htm for
additional info (CGI, examples of sending attachments,
HTML mail etc...)

You can use it freely. (Someone complained this is too
vague. So, more precisely: do whatever you want with it,
but be warned that terrible things will happen to you if
you use it badly, like for sending spam, claiming you
wrote it alone, or ...?)

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: 25.09.2000. Latest version should be avail
able at http://alma.ch/perl/mail.htm , and a few days
later on CPAN.

perl v5.8.0 2000-09-25 Sendmail(3)