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

NAME

6       Mail::Sendmail - 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 takes a hash with the message to send and sends it to
25       your mail server. It is intended to be very easy to setup and use. See
26       also "FEATURES" below, and as usual, read this documentation.
27
28       There is also a FAQ (see "NOTES").
29

INSTALLATION

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

FEATURES

67       Automatic time zone detection, Date: header, MIME quoted-printable
68       encoding (if MIME::QuotedPrint installed), all of which can be
69       overridden.
70
71       Bcc: and Cc: support.
72
73       Allows real names in From:, To: and Cc: fields
74
75       Doesn't send an X-Mailer: header (unless you do), and allows you to
76       send any header(s) you want.
77
78       Configurable retries and use of alternate servers if your mail server
79       is down
80
81       Good plain text error reporting
82
83       Experimental support for SMTP AUTHentication
84

LIMITATIONS

86       Headers are not encoded, even if they have accented characters.
87
88       Since the whole message is in memory, it's not suitable for sending
89       very big attached files.
90
91       The SMTP server has to be set manually in Sendmail.pm or in your
92       script, unless you have a mail server on localhost.
93
94       Doesn't work on OpenVMS, I was told. Cannot test this myself.
95

CONFIGURATION

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

DETAILS

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

ANOTHER EXAMPLE

332         use Mail::Sendmail;
333
334         print "Testing Mail::Sendmail version $Mail::Sendmail::VERSION\n";
335         print "Default server: $Mail::Sendmail::mailcfg{smtp}->[0]\n";
336         print "Default sender: $Mail::Sendmail::mailcfg{from}\n";
337
338         %mail = (
339             #To      => 'No to field this time, only Bcc and Cc',
340             #From    => 'not needed, use default',
341             Bcc     => 'Someone <him@there.com>, Someone else her@there.com',
342             # only addresses are extracted from Bcc, real names disregarded
343             Cc      => 'Yet someone else <xz@whatever.com>',
344             # Cc will appear in the header. (Bcc will not)
345             Subject => 'Test message',
346             'X-Mailer' => "Mail::Sendmail version $Mail::Sendmail::VERSION",
347         );
348
349
350         $mail{Smtp} = 'special_server.for-this-message-only.domain.com';
351         $mail{'X-custom'} = 'My custom additionnal header';
352         $mail{'mESSaGE : '} = "The message key looks terrible, but works.";
353         # cheat on the date:
354         $mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 );
355
356         if (sendmail %mail) { print "Mail sent OK.\n" }
357         else { print "Error sending mail: $Mail::Sendmail::error \n" }
358
359         print "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;
360
361       Also see http://alma.ch/perl/Mail-Sendmail-FAQ.html for examples of
362       HTML mail and sending attachments.
363

CHANGES

365       Main changes since version 0.79:
366
367       Experimental SMTP AUTH support (LOGIN PLAIN CRAM-MD5 DIGEST-MD5)
368
369       Fix bug where one refused RCPT TO: would abort everything
370
371       send EHLO, and parse response
372
373       Better handling of multi-line responses, and better error-messages
374
375       Non-conforming line-endings also normalized in headers
376
377       Now keeps the Sender header if it was used. Previous versions only used
378       it for the MAIL FROM: command and deleted it.
379
380       See the Changes file for the full history. If you don't have it because
381       you installed through PPM, you can also find the latest one on
382       http://alma.ch/perl/scripts/Sendmail/Changes.
383

NOTES

385       MIME::QuotedPrint is used by default on every message if available. It
386       allows reliable sending of accented characters, and also takes care of
387       too long lines (which can happen in HTML mails). It is available in the
388       MIME-Base64 package at http://www.perl.com/CPAN/modules/by-module/MIME/
389       or through PPM.
390
391       Look at http://alma.ch/perl/Mail-Sendmail-FAQ.html for additional info
392       (CGI, examples of sending attachments, HTML mail etc...)
393
394       You can use this module freely. (Someone complained this is too vague.
395       So, more precisely: do whatever you want with it, but be warned that
396       terrible things will happen to you if you use it badly, like for
397       sending spam, or ...?)
398
399       Thanks to the many users who sent me feedback, bug reports,
400       suggestions, etc.  And please excuse me if I forgot to answer your
401       mail. I am not always reliabe in answering mail. I intend to set up a
402       mailing list soon.
403
404       Last revision: 06.02.2003. Latest version should be available on CPAN:
405       http://www.cpan.org/modules/by-authors/id/M/MI/MIVKOVIC/.
406

AUTHOR

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

COPYRIGHT

411       Copyright (c) 1998-2017 Milivoj Ivkovic.  All rights reserved.  This
412       program is free software; you can redistribute it and/or modify it
413       under the same terms as Perl itself.
414
415
416
417perl v5.32.0                      2020-07-28                 Mail::Sendmail(3)