"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 NAME
2 Mail::Sendmail v. 0.79_16 - Simple platform independent mailer
3
4 SYNOPSIS
5 use Mail::Sendmail;
6
7 %mail = ( To => 'you@there.com',
8 From => 'me@here.com',
9 Message => "This is a very short message"
10 );
11
12 sendmail(%mail) or die $Mail::Sendmail::error;
13
14 print "OK. Log says:\n", $Mail::Sendmail::log;
15
16 DESCRIPTION
17 Simple platform independent e-mail from your perl script. Only requires
18 Perl 5 and a network connection.
19
20 Mail::Sendmail takes a hash with the message to send and sends it to
21 your mail server. It is intended to be very easy to setup and use. See
22 also "FEATURES" below, and as usual, read this documentation.
23
24 There is also a FAQ (see "NOTES").
25
26 INSTALLATION
27 Best
28 "perl -MCPAN -e "install Mail::Sendmail""
29
30 Traditional
31 perl Makefile.PL
32 make
33 make test
34 make install
35
36 Manual
37 Copy Sendmail.pm to Mail/ in your Perl lib directory.
38
39 (eg. c:\Perl\site\lib\Mail\
40 or /usr/lib/perl5/site_perl/Mail/
41 or whatever it is on your system.
42 They are listed when you type C< perl -V >)
43
44 ActivePerl's PPM
45 Depending on your PPM version:
46
47 ppm install --location=http://alma.ch/perl/ppm Mail-Sendmail
48
49 or
50
51 ppm install http://alma.ch/perl/ppm/Mail-Sendmail.ppd
52
53 But this way you don't get a chance to have a look at other files
54 (Changes, Todo, test.pl, ...).
55
56 At the top of Sendmail.pm, set your default SMTP server(s), unless you
57 specify it with each message, or want to use the default (localhost).
58
59 Install MIME::QuotedPrint. This is not required but strongly
60 recommended.
61
62 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 Bcc: and Cc: support.
68
69 Allows real names in From:, To: and Cc: fields
70
71 Doesn't send an X-Mailer: header (unless you do), and allows you to send
72 any header(s) you want.
73
74 Configurable retries and use of alternate servers if your mail server is
75 down
76
77 Good plain text error reporting
78
79 Experimental support for SMTP AUTHentication
80
81 LIMITATIONS
82 Headers are not encoded, even if they have accented characters.
83
84 Since the whole message is in memory, it's not suitable for sending very
85 big attached files.
86
87 The SMTP server has to be set manually in Sendmail.pm or in your script,
88 unless you have a mail server on localhost.
89
90 Doesn't work on OpenVMS, I was told. Cannot test this myself.
91
92 CONFIGURATION
93 Default SMTP server(s)
94 This is probably all you want to configure. It is usually done
95 through *$mailcfg{smtp}*, which you can edit at the top of the
96 Sendmail.pm file. This is a reference to a list of SMTP servers. You
97 can also set it from your script:
98
99 "unshift @{$Mail::Sendmail::mailcfg{'smtp'}} , 'my.mail.server';"
100
101 Alternatively, you can specify the server in the *%mail* hash you
102 send from your script, which will do the same thing:
103
104 "$mail{smtp} = 'my.mail.server';"
105
106 A future version will (hopefully) try to set useful defaults for you
107 during the Makefile.PL.
108
109 Other configuration settings
110 See *%mailcfg* under "DETAILS" below for other configuration
111 options.
112
113 DETAILS
114 sendmail()
115 sendmail is the only thing exported to your namespace by default
116
117 "sendmail(%mail) || print "Error sending mail:
118 $Mail::Sendmail::error\n";"
119
120 It takes a hash containing the full message, with keys for all headers
121 and the body, as well as for some specific options.
122
123 It returns 1 on success or 0 on error, and rewrites
124 $Mail::Sendmail::error and $Mail::Sendmail::log.
125
126 Keys are NOT case-sensitive.
127
128 The colon after headers is not necessary.
129
130 The Body part key can be called 'Body', 'Message' or 'Text'.
131
132 The SMTP server key can be called 'Smtp' or 'Server'. If the connection
133 to this one fails, the other ones in $mailcfg{smtp} will still be tried.
134
135 The following headers are added unless you specify them yourself:
136
137 Mime-Version: 1.0
138 Content-Type: 'text/plain; charset="iso-8859-1"'
139
140 Content-Transfer-Encoding: quoted-printable
141 or (if MIME::QuotedPrint not installed)
142 Content-Transfer-Encoding: 8bit
143
144 Date: [string returned by time_to_date()]
145
146 If you wish to use an envelope sender address different than the From:
147 address, set $mail{Sender} in your %mail hash.
148
149 The following are not exported by default, but you can still access them
150 with their full name, or request their export on the use line like in:
151 "use Mail::Sendmail qw(sendmail $address_rx time_to_date);"
152
153 embedding options in your %mail hash
154 The following options can be set in your %mail hash. The corresponding
155 keys will be removed before sending the mail.
156
157 $mail{smtp} or $mail{server}
158 The SMTP server to try first. It will be added
159
160 $mail{port}
161 This option will be removed. To use a non-standard port, set it in
162 your server name:
163
164 $mail{server}='my.smtp.server:2525' will try to connect to port 2525
165 on server my.smtp.server
166
167 $mail{auth}
168 This must be a reference to a hash containg all your authentication
169 options:
170
171 $mail{auth} = \%options; or $mail{auth} = {user=>"username",
172 password=>"password", method=>"DIGEST-MD5", required=>0 };
173
174 user
175 username
176
177 pass or password
178 password
179
180 method
181 optional method. compared (stripped down) to available methods.
182 If empty, will try all available.
183
184 required
185 optional. defaults to false. If set to true, no delivery will be
186 attempted if authentication fails. If false or undefined, and
187 authentication fails or is not available, sending is tried
188 without.
189
190 (different auth for different servers?)
191
192 Mail::Sendmail::time_to_date()
193 convert time ( as from "time()" ) to an RFC 822 compliant string for the
194 Date header. See also "%Mail::Sendmail::mailcfg".
195
196 $Mail::Sendmail::error
197 When you don't run with the -w flag, the module sends no errors to
198 STDERR, but puts anything it has to complain about in here. You should
199 probably always check if it says something.
200
201 $Mail::Sendmail::log
202 A summary that you could write to a log file after each send
203
204 $Mail::Sendmail::address_rx
205 A handy regex to recognize e-mail addresses.
206
207 A correct regex for valid e-mail addresses was written by one of the
208 judges in the obfuscated Perl contest... :-) It is quite big. This one
209 is an attempt to a reasonable compromise, and should accept all
210 real-world internet style addresses. The domain part is required and
211 comments or characters that would need to be quoted are not supported.
212
213 Example:
214 $rx = $Mail::Sendmail::address_rx;
215 if (/$rx/) {
216 $address=$1;
217 $user=$2;
218 $domain=$3;
219 }
220
221 %Mail::Sendmail::mailcfg
222 This hash contains installation-wide configuration options. You normally
223 edit it once (if ever) in Sendmail.pm and forget about it, but you could
224 also access it from your scripts. For readability, I'll assume you have
225 imported it (with something like "use Mail::Sendmail qw(sendmail
226 %mailcfg)").
227
228 The keys are not case-sensitive: they are all converted to lowercase
229 before use. Writing "$mailcfg{Port} = 2525;" is OK: the default
230 $mailcfg{port} (25) will be deleted and replaced with your new value of
231 2525.
232
233 $mailcfg{smtp}
234 "$mailcfg{smtp} = [qw(localhost my.other.mail.server)];"
235
236 This is a reference to a list of smtp servers, so if your main
237 server is down, the module tries the next one. If one of your
238 servers uses a special port, add it to the server name with a colon
239 in front, to override the default port (like in
240 my.special.server:2525).
241
242 Default: localhost.
243
244 $mailcfg{from}
245 "$mailcfg{from} = 'Mailing script me@mydomain.com';"
246
247 From address used if you don't supply one in your script. Should not
248 be of type 'user@localhost' since that may not be valid on the
249 recipient's host.
250
251 Default: undefined.
252
253 $mailcfg{mime}
254 "$mailcfg{mime} = 1;"
255
256 Set this to 0 if you don't want any automatic MIME encoding. You
257 normally don't need this, the module should 'Do the right thing'
258 anyway.
259
260 Default: 1;
261
262 $mailcfg{retries}
263 "$mailcfg{retries} = 1;"
264
265 How many times should the connection to the same SMTP server be
266 retried in case of a failure.
267
268 Default: 1;
269
270 $mailcfg{delay}
271 "$mailcfg{delay} = 1;"
272
273 Number of seconds to wait between retries. This delay also happens
274 before trying the next server in the list, if the retries for the
275 current server have been exhausted. For CGI scripts, you want few
276 retries and short delays to return with a results page before the
277 http connection times out. For unattended scripts, you may want to
278 use many retries and long delays to have a good chance of your mail
279 being sent even with temporary failures on your network.
280
281 Default: 1 (second);
282
283 $mailcfg{tz}
284 "$mailcfg{tz} = '+0800';"
285
286 Normally, your time zone is set automatically, from the difference
287 between "time()" and "gmtime()". This allows you to override
288 automatic detection in cases where your system is confused (such as
289 some Win32 systems in zones which do not use daylight savings time:
290 see Microsoft KB article Q148681)
291
292 Default: undefined (automatic detection at run-time).
293
294 $mailcfg{port}
295 "$mailcfg{port} = 25;"
296
297 Port used when none is specified in the server name.
298
299 Default: 25.
300
301 $mailcfg{debug}
302 "$mailcfg{debug} = 0;"
303
304 Prints stuff to STDERR. Current maximum is 6, which prints the whole
305 SMTP session, except data exceeding 500 bytes.
306
307 Default: 0;
308
309 $Mail::Sendmail::VERSION
310 The package version number (you can not import this one)
311
312 Configuration variables from previous versions
313 The following global variables were used in version 0.74 for
314 configuration. As from version 0.78_1, they are not supported anymore.
315 Use the *%mailcfg* hash if you need to access the configuration from
316 your scripts.
317
318 $Mail::Sendmail::default_smtp_server
319 $Mail::Sendmail::default_smtp_port
320 $Mail::Sendmail::default_sender
321 $Mail::Sendmail::TZ
322 $Mail::Sendmail::connect_retries
323 $Mail::Sendmail::retry_delay
324 $Mail::Sendmail::use_MIME
325
326 ANOTHER EXAMPLE
327 use Mail::Sendmail;
328
329 print "Testing Mail::Sendmail version $Mail::Sendmail::VERSION\n";
330 print "Default server: $Mail::Sendmail::mailcfg{smtp}->[0]\n";
331 print "Default sender: $Mail::Sendmail::mailcfg{from}\n";
332
333 %mail = (
334 #To => 'No to field this time, only Bcc and Cc',
335 #From => 'not needed, use default',
336 Bcc => 'Someone <him@there.com>, Someone else her@there.com',
337 # only addresses are extracted from Bcc, real names disregarded
338 Cc => 'Yet someone else <xz@whatever.com>',
339 # Cc will appear in the header. (Bcc will not)
340 Subject => 'Test message',
341 'X-Mailer' => "Mail::Sendmail version $Mail::Sendmail::VERSION",
342 );
343
344 $mail{Smtp} = 'special_server.for-this-message-only.domain.com';
345 $mail{'X-custom'} = 'My custom additionnal header';
346 $mail{'mESSaGE : '} = "The message key looks terrible, but works.";
347 # cheat on the date:
348 $mail{Date} = Mail::Sendmail::time_to_date( time() - 86400 );
349
350 if (sendmail %mail) { print "Mail sent OK.\n" }
351 else { print "Error sending mail: $Mail::Sendmail::error \n" }
352
353 print "\n\$Mail::Sendmail::log says:\n", $Mail::Sendmail::log;
354
355 Also see http://alma.ch/perl/Mail-Sendmail-FAQ.html for examples of HTML
356 mail and sending attachments.
357
358 CHANGES
359 Main changes since version 0.79:
360
361 Experimental SMTP AUTH support (LOGIN PLAIN CRAM-MD5 DIGEST-MD5)
362
363 Fix bug where one refused RCPT TO: would abort everything
364
365 send EHLO, and parse response
366
367 Better handling of multi-line responses, and better error-messages
368
369 Non-conforming line-endings also normalized in headers
370
371 Now keeps the Sender header if it was used. Previous versions only used
372 it for the MAIL FROM: command and deleted it.
373
374 See the Changes file for the full history. If you don't have it because
375 you installed through PPM, you can also find the latest one on
376 http://alma.ch/perl/scripts/Sendmail/Changes.
377
378 AUTHOR
379 Milivoj Ivkovic <mi\x40alma.ch> ("\x40" is "@" of course)
380
381 NOTES
382 MIME::QuotedPrint is used by default on every message if available. It
383 allows reliable sending of accented characters, and also takes care of
384 too long lines (which can happen in HTML mails). It is available in the
385 MIME-Base64 package at http://www.perl.com/CPAN/modules/by-module/MIME/
386 or through PPM.
387
388 Look at http://alma.ch/perl/Mail-Sendmail-FAQ.html for additional info
389 (CGI, examples of sending attachments, HTML mail etc...)
390
391 You can use this module freely. (Someone complained this is too vague.
392 So, more precisely: do whatever you want with it, but be warned that
393 terrible things will happen to you if you use it badly, like for sending
394 spam, or ...?)
395
396 Thanks to the many users who sent me feedback, bug reports, suggestions,
397 etc. And please excuse me if I forgot to answer your mail. I am not
398 always reliabe in answering mail. I intend to set up a mailing list
399 soon.
400
401 Last revision: 06.02.2003. Latest version should be available on CPAN:
402 http://www.cpan.org/modules/by-authors/id/M/MI/MIVKOVIC/.
403