1Sendmail(3)           User Contributed Perl Documentation          Sendmail(3)
2
3
4

NAME

6       Mail::Sendmail v. 0.79 - Simple platform independent mailer
7

SYNOPSIS

9         use Mail::Sendmail;
10
11         %mail = ( To      => 'you@there.com',
12                   From    => 'me@here.com',
13                   Message => "This is a very short message"
14                  );
15
16         sendmail(%mail) or die $Mail::Sendmail::error;
17
18         print "OK. Log says:\n", $Mail::Sendmail::log;
19

DESCRIPTION

21       Simple platform independent e-mail from your perl script. Only requires
22       Perl 5 and a network connection.
23
24       Mail::Sendmail contains mainly &sendmail, which takes a hash with the
25       message to send and sends it. It is intended to be very easy to setup
26       and use. See also "FEATURES" below.
27

INSTALLATION

29       Best
30           "perl -MCPAN -e "install Mail::Sendmail""
31
32       Traditional
33               perl Makefile.PL
34               make
35               make test
36               make install
37
38       Manual
39           Copy Sendmail.pm to Mail/ in your Perl lib directory.
40
41               (eg. c:\Perl\site\lib\Mail\
42                or  /usr/lib/perl5/site_perl/Mail/
43                or whatever it is on your system.
44                They are listed when you type C< perl -V >)
45
46       ActivePerl's PPM
47           ppm install --location=http://alma.ch/perl/ppm Mail-Sendmail
48
49           But this way you don't get a chance to have a look at other files
50           (Changes, Todo, test.pl, ...).
51
52       At the top of Sendmail.pm, set your default SMTP server(s), unless you
53       specify it with each message, or want to use the default (localhost).
54
55       Install MIME::QuotedPrint. This is not required but strongly recom‐
56       mended.
57

FEATURES

59       Automatic time zone detection, Date: header, MIME quoted-printable
60       encoding (if MIME::QuotedPrint installed), all of which can be overrid‐
61       den.
62
63       Bcc: and Cc: support.
64
65       Allows real names in From:, To: and Cc: fields
66
67       Doesn't send an X-Mailer: header (unless you do), and allows you to
68       send any header(s) you want.
69
70       Configurable retries and use of alternate servers if your mail server
71       is down
72
73       Good plain text error reporting
74

LIMITATIONS

76       Headers are not encoded, even if they have accented characters.
77
78       No suport for the SMTP AUTH extension.
79
80       Since the whole message is in memory, it's not suitable for sending
81       very big attached files.
82
83       The SMTP server has to be set manually in Sendmail.pm or in your
84       script, unless you have a mail server on localhost.
85
86       Doesn't work on OpenVMS, I was told. Cannot test this myself.
87

CONFIGURATION

89       Default SMTP server(s)
90           This is probably all you want to configure. It is usually done
91           through $mailcfg{smtp}, which you can edit at the top of the Send‐
92           mail.pm file.  This is a reference to a list of SMTP servers. You
93           can also set it from your script:
94
95           "unshift @{$Mail::Sendmail::mailcfg{'smtp'}} , 'my.mail.server';"
96
97           Alternatively, you can specify the server in the %mail hash you
98           send from your script, which will do the same thing:
99
100           "$mail{smtp} = 'my.mail.server';"
101
102           A future version will (hopefully) try to set useful defaults for
103           you during the Makefile.PL.
104
105       Other configuration settings
106           See %mailcfg under "DETAILS" below for other configuration options.
107

DETAILS

109       sendmail()
110
111       sendmail is the only thing exported to your namespace by default
112
113       "sendmail(%mail) ⎪⎪ print "Error sending mail: $Mail::Send‐
114       mail::error\n";"
115
116       It takes a hash containing the full message, with keys for all headers,
117       body, and optionally for another non-default SMTP server and/or port.
118
119       It returns 1 on success or 0 on error, and rewrites $Mail::Send‐
120       mail::error and $Mail::Sendmail::log.
121
122       Keys are NOT case-sensitive.
123
124       The colon after headers is not necessary.
125
126       The Body part key can be called 'Body', 'Message' or 'Text'.
127
128       The SMTP server key can be called 'Smtp' or 'Server'. If the connection
129       to this one fails, the other ones in $mailcfg{smtp} will still be
130       tried.
131
132       The following headers are added unless you specify them yourself:
133
134           Mime-Version: 1.0
135           Content-Type: 'text/plain; charset="iso-8859-1"'
136
137           Content-Transfer-Encoding: quoted-printable
138           or (if MIME::QuotedPrint not installed)
139           Content-Transfer-Encoding: 8bit
140
141           Date: [string returned by time_to_date()]
142
143       If you wish to use an envelope sender address different than the From:
144       address, set $mail{Sender} in your %mail hash.
145
146       The following are not exported by default, but you can still access
147       them with their full name, or request their export on the use line like
148       in: "use Mail::Sendmail qw(sendmail $address_rx time_to_date);"
149
150       Mail::Sendmail::time_to_date()
151
152       convert time ( as from "time()" ) to an RFC 822 compliant string for
153       the Date header. See also "%Mail::Sendmail::mailcfg".
154
155       $Mail::Sendmail::error
156
157       When you don't run with the -w flag, the module sends no errors to
158       STDERR, but puts anything it has to complain about in here. You should
159       probably always check if it says something.
160
161       $Mail::Sendmail::log
162
163       A summary that you could write to a log file after each send
164
165       $Mail::Sendmail::address_rx
166
167       A handy regex to recognize e-mail addresses.
168
169       A correct regex for valid e-mail addresses was written by one of the
170       judges in the obfuscated Perl contest... :-) It is quite big. This one
171       is an attempt to a reasonable compromise, and should accept all real-
172       world internet style addresses. The domain part is required and com‐
173       ments or characters that would need to be quoted are not supported.
174
175         Example:
176           $rx = $Mail::Sendmail::address_rx;
177           if (/$rx/) {
178             $address=$1;
179             $user=$2;
180             $domain=$3;
181           }
182
183       %Mail::Sendmail::mailcfg
184
185       This hash contains all configuration options. You normally edit it once
186       (if ever) in Sendmail.pm and forget about it, but you could also access
187       it from your scripts. For readability, I'll assume you have imported it
188       (with something like "use Mail::Sendmail qw(sendmail %mailcfg)").
189
190       The keys are not case-sensitive: they are all converted to lowercase
191       before use. Writing "$mailcfg{Port} = 2525;" is OK: the default $mail‐
192       cfg{port} (25) will be deleted and replaced with your new value of
193       2525.
194
195       $mailcfg{smtp}
196           "$mailcfg{smtp} = [qw(localhost my.other.mail.server)];"
197
198           This is a reference to a list of smtp servers, so if your main
199           server is down, the module tries the next one. If one of your
200           servers uses a special port, add it to the server name with a colon
201           in front, to override the default port (like in my.spe‐
202           cial.server:2525).
203
204           Default: localhost.
205
206       $mailcfg{from}
207           "$mailcfg{from} = 'Mailing script me@mydomain.com';"
208
209           From address used if you don't supply one in your script. Should
210           not be of type 'user@localhost' since that may not be valid on the
211           recipient's host.
212
213           Default: undefined.
214
215       $mailcfg{mime}
216           "$mailcfg{mime} = 1;"
217
218           Set this to 0 if you don't want any automatic MIME encoding. You
219           normally don't need this, the module should 'Do the right thing'
220           anyway.
221
222           Default: 1;
223
224       $mailcfg{retries}
225           "$mailcfg{retries} = 1;"
226
227           How many times should the connection to the same SMTP server be
228           retried in case of a failure.
229
230           Default: 1;
231
232       $mailcfg{delay}
233           "$mailcfg{delay} = 1;"
234
235           Number of seconds to wait between retries. This delay also happens
236           before trying the next server in the list, if the retries for the
237           current server have been exhausted. For CGI scripts, you want few
238           retries and short delays to return with a results page before the
239           http connection times out. For unattended scripts, you may want to
240           use many retries and long delays to have a good chance of your mail
241           being sent even with temporary failures on your network.
242
243           Default: 1 (second);
244
245       $mailcfg{tz}
246           "$mailcfg{tz} = '+0800';"
247
248           Normally, your time zone is set automatically, from the difference
249           between "time()" and "gmtime()". This allows you to override auto‐
250           matic detection in cases where your system is confused (such as
251           some Win32 systems in zones which do not use daylight savings time:
252           see Microsoft KB article Q148681)
253
254           Default: undefined (automatic detection at run-time).
255
256       $mailcfg{port}
257           "$mailcfg{port} = 25;"
258
259           Port used when none is specified in the server name.
260
261           Default: 25.
262
263       $mailcfg{debug}
264           "$mailcfg{debug} = 0;"
265
266           Prints stuff to STDERR. Current maximum is 6, which prints the
267           whole SMTP session, except data exceeding 500 bytes.
268
269           Default: 0;
270
271       $Mail::Sendmail::VERSION
272
273       The package version number (you can not import this one)
274
275       Configuration variables from previous versions
276
277       The following global variables were used in version 0.74 for configura‐
278       tion.  As from version 0.78_1, they are not supported anymore.  Use the
279       %mailcfg hash if you need to access the configuration from your
280       scripts.
281
282       $Mail::Sendmail::default_smtp_server
283       $Mail::Sendmail::default_smtp_port
284       $Mail::Sendmail::default_sender
285       $Mail::Sendmail::TZ
286       $Mail::Sendmail::connect_retries
287       $Mail::Sendmail::retry_delay
288       $Mail::Sendmail::use_MIME
289

ANOTHER EXAMPLE

291         use Mail::Sendmail;
292
293         print "Testing Mail::Sendmail version $Mail::Sendmail::VERSION\n";
294         print "Default server: $Mail::Sendmail::mailcfg{smtp}->[0]\n";
295         print "Default sender: $Mail::Sendmail::mailcfg{from}\n";
296
297         %mail = (
298             #To      => 'No to field this time, only Bcc and Cc',
299             #From    => 'not needed, use default',
300             Bcc     => 'Someone <him@there.com>, Someone else her@there.com',
301             # only addresses are extracted from Bcc, real names disregarded
302             Cc      => 'Yet someone else <xz@whatever.com>',
303             # Cc will appear in the header. (Bcc will not)
304             Subject => 'Test message',
305             'X-Mailer' => "Mail::Sendmail version $Mail::Sendmail::VERSION",
306         );
307
308         $mail{Smtp} = 'special_server.for-this-message-only.domain.com';
309         $mail{'X-custom'} = 'My custom additionnal header';
310         $mail{'mESSaGE : '} = "The message key looks terrible, but works.";
311         # cheat on the date:
312         $mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 );
313
314         if (sendmail %mail) { print "Mail sent OK.\n" }
315         else { print "Error sending mail: $Mail::Sendmail::error \n" }
316
317         print "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;
318
319       Also see http://alma.ch/perl/Mail-Sendmail-FAQ.html for examples of
320       HTML mail and sending attachments.
321

CHANGES

323       Main changes since version 0.78:
324
325       Added "/" (\x2F) as a valid character in mailbox part.
326
327       Removed old configuration variables which are not used anymore since
328       version 0.74.
329
330       Added support for different envelope sender (through $mail{Sender})
331
332       Changed case of headers: first character after "-" also uppercased
333
334       Support for multi-line server responses
335
336       Localized $\ and $_
337
338       Some internal rewrites and documentation updates
339
340       Fixed old bug of dot as 76th character on line disappearing.
341
342       Fixed very old bug where port number was not extracted from stuff like
343       'my.server:2525'.
344
345       Fixed time_to_date bug with negative half-hour zones (only Newfound‐
346       land?)
347
348       Added seconds to date string
349
350       Now uses Sys::Hostname to get the hostname for HELO. (This may break
351       the module on some very old Win32 Perls where Sys::Hostname was broken)
352
353       Enable full session output for debugging
354
355       See the Changes file for the full history. If you don't have it because
356       you installed through PPM, you can also find the latest one on
357       http://alma.ch/perl/scripts/Sendmail/Changes.
358

AUTHOR

360       Milivoj Ivkovic <mi\x40alma.ch> ("\x40" is "@" of course)
361

NOTES

363       MIME::QuotedPrint is used by default on every message if available. It
364       allows reliable sending of accented characters, and also takes care of
365       too long lines (which can happen in HTML mails). It is available in the
366       MIME-Base64 package at http://www.perl.com/CPAN/modules/by-module/MIME/
367       or through PPM.
368
369       Look at http://alma.ch/perl/Mail-Sendmail-FAQ.html for additional info
370       (CGI, examples of sending attachments, HTML mail etc...)
371
372       You can use this module freely. (Someone complained this is too vague.
373       So, more precisely: do whatever you want with it, but be warned that
374       terrible things will happen to you if you use it badly, like for send‐
375       ing spam, or ...?)
376
377       Thanks to the many users who sent me feedback, bug reports, sugges‐
378       tions, etc.  And please excuse me if I forgot to answer your mail. I am
379       not always reliabe in answering mail. I intend to set up a mailing list
380       soon.
381
382       Last revision: 06.02.2003. Latest version should be available on CPAN:
383       http://www.cpan.org/modules/by-authors/id/M/MI/MIVKOVIC/.
384
385
386
387perl v5.8.8                       2003-02-06                       Sendmail(3)