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

NAME

6       Mail::Sendmail v. 0.78 - 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       After struggling for some time with various command-line mailing
25       programs which never did exactly what I wanted, I put together this
26       Perl only solution.
27
28       Mail::Sendmail contains mainly &sendmail, which takes a hash with the
29       message to send and sends it. It is intended to be very easy to setup
30       and use.
31

INSTALLATION

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

FEATURES

63       Automatic time zone detection, Date: header, MIME quoted-printable
64       encoding (if MIME::QuotedPrint installed), all of which can be
65       overridden.
66
67       Internal Bcc: and Cc: support (even on broken servers)
68
69       Allows real names in From: and To: fields
70
71       Doesn't send unwanted headers, and allows you to send any header(s) you
72       want
73
74       Configurable retries and use of alternate servers if your mail server
75       is down
76
77       Good plain text error reporting
78

LIMITATIONS

80       Doesn't work on OpenVMS.
81
82       Headers are not encoded, even if they have accented characters.
83
84       Since the whole message is in memory (twice!), it's not suitable for
85       sending very big attached files.
86
87       The SMTP server has to be set manually in Sendmail.pm or in your
88       script, unless you have a mail server on localhost.
89

CONFIGURATION

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

DETAILS

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

ANOTHER EXAMPLE

282         use Mail::Sendmail;
283
284         print "Testing Mail::Sendmail version $Mail::Sendmail::VERSION\n";
285         print "Default server: $Mail::Sendmail::mailcfg{smtp}->[0]\n";
286         print "Default sender: $Mail::Sendmail::mailcfg{from}\n";
287
288         %mail = (
289             #To      => 'No to field this time, only Bcc and Cc',
290             #From    => 'not needed, use default',
291             Bcc     => 'Someone <him@there.com>, Someone else her@there.com',
292             # only addresses are extracted from Bcc, real names disregarded
293             Cc      => 'Yet someone else <xz@whatever.com>',
294             # Cc will appear in the header. (Bcc will not)
295             Subject => 'Test message',
296             'X-Mailer' => "Mail::Sendmail version $Mail::Sendmail::VERSION",
297         );
298
299
300         $mail{Smtp} = 'special_server.for-this-message-only.domain.com';
301         $mail{'X-custom'} = 'My custom additionnal header';
302         $mail{'mESSaGE : '} = "The message key looks terrible, but works.";
303         # cheat on the date:
304         $mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 ),
305
306         if (sendmail %mail) { print "Mail sent OK.\n" }
307         else { print "Error sending mail: $Mail::Sendmail::error \n" }
308
309         print "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;
310

CHANGES

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

AUTHOR

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

NOTES

319       MIME::QuotedPrint is used by default on every message if available. It
320       allows reliable sending of accented characters, and also takes care of
321       too long lines (which can happen in HTML mails). It is available in the
322       MIME-Base64 package at http://www.perl.com/CPAN/modules/by-module/MIME/
323       or through PPM.
324
325       Look at http://alma.ch/perl/Mail-Sendmail-FAQ.htm for additional info
326       (CGI, examples of sending attachments, HTML mail etc...)
327
328       You can use it freely. (Someone complained this is too vague. So, more
329       precisely: do whatever you want with it, but be warned that terrible
330       things will happen to you if you use it badly, like for sending spam,
331       claiming you wrote it alone, or ...?)
332
333       I would appreciate a short (or long) e-mail note if you use this (and
334       even if you don't, especially if you care to say why). And of course,
335       bug-reports and/or suggestions are welcome.
336
337       Last revision: 25.09.2000. Latest version should be available at
338       http://alma.ch/perl/mail.htm , and a few days later on CPAN.
339
340
341
342perl v5.30.1                      2020-02-10            inc::Mail::Sendmail(3)
Impressum