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

NAME

6       Mail::Sender - module for sending mails with attachments through an
7       SMTP server
8
9       Version 0.8.13
10

SYNOPSIS

12        use Mail::Sender;
13        $sender = new Mail::Sender
14         {smtp => 'mail.yourdomain.com', from => 'your@address.com'};
15        $sender->MailFile({to => 'some@address.com',
16         subject => 'Here is the file',
17         msg => "I'm sending you the list you wanted.",
18         file => 'filename.txt'});
19

DESCRIPTION

21       "Mail::Sender" provides an object oriented interface to sending mails.
22       It doesn't need any outer program. It connects to a mail server
23       directly from Perl, using Socket.
24
25       Sends mails directly from Perl through a socket connection.
26

new Mail::Sender

28        new Mail::Sender ([from [,replyto [,to [,smtp [,subject [,headers [,boundary]]]]]]])
29        new Mail::Sender {[from => 'somebody@somewhere.com'] , [to => 'else@nowhere.com'] [...]}
30
31       Prepares a sender. This doesn't start any connection to the server. You
32       have to use "$Sender-"Open> or "$Sender-"OpenMultipart> to start talk‐
33       ing to the server.
34
35       The parameters are used in subsequent calls to "$Sender-"Open> and
36       "$Sender-"OpenMultipart>. Each such call changes the saved variables.
37       You can set "smtp", "from" and other options here and then use the info
38       in all messages.
39
40       Parameters
41
42       from
43           => the sender's e-mail address
44
45       fake_from
46           => the address that will be shown in headers.
47
48           If not specified we use the value of "from".
49
50       replyto
51           => the reply-to address
52
53       to  => the recipient's address(es)
54
55           This parameter may be either a comma separated list of email
56           addresses or a reference to a list of addresses.
57
58       fake_to
59           => the recipient's address that will be shown in headers.  If not
60           specified we use the value of "to".
61
62           If the list of addresses you want to send your message to is long
63           or if you do not want the recipients to see each other's address
64           set the "fake_to" parameter to some informative, yet bogus, address
65           or to the address of your mailing/distribution list.
66
67       cc  => address(es) to send a copy (CC:) to
68
69       fake_cc
70           => the address that will be shown in headers.
71
72           If not specified we use the value of "cc".
73
74       bcc => address(es) to send a copy (BCC: or blind carbon copy).  these
75           addresses will not be visible in the mail!
76
77       smtp
78           => the IP or domain address of your SMTP (mail) server
79
80           This is the name of your LOCAL mail server, do NOT try to contact
81           directly the adressee's mailserver! That would be slow and buggy,
82           your script should only pass the messages to the nearest mail
83           server and leave the rest to it. Keep in mind that the recipient's
84           server may be down temporarily.
85
86       subject
87           => the subject of the message
88
89       headers
90           => the additional headers
91
92           You may use this parameter to add custon headers into the message.
93
94       boundary
95           => the message boundary
96
97           You usualy do not have to change this, it might only come in handy
98           if you need to attach a multipart mail created by Mail::Sender to
99           your message as a single part.  Even in that case any problems are
100           unlikely.
101
102       multipart
103           => the MIME subtype for the whole message (Mixed/Related/Alterna‐
104           tive)
105
106           You may need to change this setting if you want to send a HTML body
107           with some inline images, or if you want to post the message in
108           plain text as well as HTML (alternative). See the examples at the
109           end of the docs.  You may also use the nickname "subtype".
110
111           Please keep in mind though that it's not currently possible to cre‐
112           ate nested parts with Mail::Sender.  If you need that level of con‐
113           trol you should try MIME::Lite.
114
115       ctype
116           => the content type of a single part message
117
118           Please do not confuse these two. The 'multipart' parameter is used
119           to specify the overall content type of a multipart message (for
120           example a HTML document with inlined images) while ctype is an
121           ordinary content type for a single part message. For example a HTML
122           mail message without any inlines.
123
124       encoding
125           => encoding of a single part message or the body of a multipart
126           message.
127
128           If the text of the message contains some extended characters or
129           very long lines you should use 'encoding => "Quoted-printable"' in
130           the call to Open(), OpenMultipart(), MailMsg() or MailFile().
131
132           Keep in mind that if you use some encoding you should either use
133           SendEnc() or encode the data yourself !
134
135       charset
136           => the charset of the message
137
138       client
139           => the name of the client computer.
140
141           During the connection you send the mailserver your computer's name.
142           By default Mail::Sender sends "(gethostbyname 'localhost')[0]".  If
143           that is not the address you need, you can specify a different one.
144
145       priority
146           => the message priority number
147
148           1 = highest, 2 = high, 3 = normal, 4 = low, 5 = lowest
149
150       confirm
151           => whether you request reading or delivery confirmations and to
152           what addresses:
153
154                   "delivery" - only delivery, to the C<from> address
155                   "reading" - only reading, to the C<from> address
156                   "delivery, reading" - both confirmations, to the C<from> address
157                   "delivery: my.other@address.com" - only delivery, to my.other@address.com
158                   ...
159
160           Keep in mind though that neither of those is guaranteed to work.
161           Some servers/mail clients do not support this feature and some
162           users/admins may have disabled it. So it's possible that your mail
163           was delivered and read, but you wount get any confirmation!
164
165       debug
166           => "/path/to/debug/file.txt"
167
168           or
169
170           =>  \*FILEHANDLE
171
172           or
173
174           => $FH
175
176           All the conversation with the server will be logged to that file or
177           handle.  All lines in the file should end with CRLF (the Windows
178           and Internet format).  If even a single one of them does not,
179           please let me know!
180
181           If you pass the path to the log file, Mail::Sender will overwrite
182           it. If you want to append to the file, you have to open it yourself
183           and pass the filehandle:
184
185                   open my $DEBUG, ">> /path/to/debug/file.txt"
186                           or die "Can't open the debug file: $!\n"
187                   $sender = new Mail::Sender ({
188                           ...
189                           debug => $DEBUG,
190                   });
191
192       debug_level
193           Only taken into account if the "debug" option is specified.
194
195                   1 - only log the conversation with the server, skip all message data
196                   2 - log the conversation and message headers
197                   3 - log the conversation and the message and part headers
198                   4 - log everything (default)
199
200       auth
201           the SMTP authentication protocol to use to login to the server cur‐
202           rently the only ones supported are LOGIN, PLAIN, CRAM-MD5 and NTLM.
203
204           Some protocols have module dependencies. CRAM-MD5 depends on
205           Digest::HMAC_MD5 and NTLM on Authen::NTLM.
206
207           You may add support for other authentication protocols yourself.
208           See below.
209
210       authid
211           the username used to login to the server
212
213       authpwd
214           the password used to login to the server
215
216       authdomain
217           the domain name. Used optionaly by the NTLM authentication.
218
219           Other authentication protocols may use other options as well.  They
220           should all start with "auth" though.
221
222           Please see the authentication section bellow.
223
224       auth_encoded
225           If set to a true value the LOGIN authentication assumes the authid
226           and authpwd is already base64 encoded.
227
228       keepconnection
229           If set to a true value causes the Mail::Sender to keep the connec‐
230           tion open for several messages.  The connection will be closed if
231           you call the Close() method with a true value or if you call Open,
232           OpenMultipart, MailMsg or MailFile with the "smtp" parameter.  This
233           means that if you want the object to keep the connection you should
234           pass the "smtp" either to "new Mail::Sender" or only to the first
235           Open, OpenMultipart, MailMsg or MailFile!
236
237       skip_bad_recipients
238           If this option is set to false or not specified then Mail::Sender
239           stops trying to send a message as soon as the first recipient's
240           address fails. If it is set to a true value Mail::Sender skips the
241           bad addresses and tries to send the message at least to the good
242           ones. If all addresses are rejected by the server it reports an
243           "All recipients were rejected" message.
244
245           If any addresses were skipped the "$sender->{'skipped_recipients'}"
246           will be a reference to a hash containing the failed address and the
247           server's response.
248
249       createmessageid
250           This option allows you to overwrite the function that generates the
251           message IDs for the emails.  The function gets the "pure" sender's
252           address as it's only parameter and is supposed to return a string.
253           See the MessageID subroutine in Mail::Sender.pm.
254
255           If you want to specify a message id you can also use the "mes‐
256           sageid" parameter for the Open, OpenMultipart, MailMsg or MailFile
257           methods.
258
259       on_errors
260           This option allows you to affect the way Mail::Sender reports
261           errors.
262
263                   => 'die' - raise an exception
264                   => 'code' - return the negative error code (default)
265                   => 'undef' - return an undef
266
267           $Mail::Sender::Error, $sender->{'error'} and $sender->{'error_msg'}
268           are set in all the cases.
269
270           All methods return the $sender object if they succeed.
271
272           P.S.: The die_on_errors option is deprecated. You may still use it,
273           but it may be removed in future versions!
274
275       Return codes
276
277         ref to a Mail::Sender object =  success
278
279         -1 = $smtphost unknown
280         -2 = socket() failed
281         -3 = connect() failed
282         -4 = service not available
283         -5 = unspecified communication error
284         -6 = local user $to unknown on host $smtp
285         -7 = transmission of message failed
286         -8 = argument $to empty
287         -9 = no message specified in call to MailMsg or MailFile
288         -10 = no file name specified in call to SendFile or MailFile
289         -11 = file not found
290         -12 = not available in singlepart mode
291         -13 = site specific error
292         -14 = connection not established. Did you mean MailFile instead of SendFile?
293         -15 = no SMTP server specified
294         -16 = no From: address specified
295         -17 = authentication protocol not accepted by the server
296         -18 = login not accepted
297         -19 = authentication protocol is not implemented
298
299       $Mail::Sender::Error contains a textual description of last error.
300

METHODS

302       Open
303
304        Open([from [, replyto [, to [, smtp [, subject [, headers]]]]]])
305        Open({[from => "somebody@somewhere.com"] , [to => "else@nowhere.com"] [...]})
306
307       Opens a new message. If some parameters are unspecified or empty, it
308       uses the parameters passed to the ""$Sender=new Mail::Sender(...)"";
309
310       See "new Mail::Sender" for info about the parameters.
311
312       The only additional parameter that may not be specified directly in the
313       "new Mail::Sender" is messageid. If you set this option then the mes‐
314       sage will be sent with this Message-ID, otherwise a new Message ID will
315       be generated out of the sender's address, current date+time and a ran‐
316       dom number (or by the function you specified in the "createmessageid"
317       option).
318
319       After the message is sent "$sender-<{messageid}" will contain the Mes‐
320       sage-ID with which the message was sent.
321
322       Returns ref to the Mail::Sender object if successfull.
323
324       OpenMultipart
325
326        OpenMultipart([from [, replyto [, to [, smtp [, subject [, headers [, boundary]]]]]]])
327        OpenMultipart({[from => "somebody@somewhere.com"] , [to => "else@nowhere.com"] [...]})
328
329       Opens a multipart message. If some parameters are unspecified or empty,
330       it uses the parameters passed to the "$Sender=new Mail::Sender(...)".
331
332       See "new Mail::Sender" for info about the parameters.
333
334       Returns ref to the Mail::Sender object if successfull.
335
336       MailMsg
337
338        MailMsg([from [, replyto [, to [, smtp [, subject [, headers]]]]]], message)
339        MailMsg({[from => "somebody@somewhere.com"]
340                 [, to => "else@nowhere.com"] [...], msg => "Message"})
341
342       Sends a message. If a mail in $sender is opened it gets closed and a
343       new mail is created and sent. $sender is then closed.  If some parame‐
344       ters are unspecified or empty, it uses the parameters passed to the
345       ""$Sender=new Mail::Sender(...)"";
346
347       See "new Mail::Sender" for info about the parameters.
348
349       The module was made so that you could create an object initialized with
350       all the necesary options and then send several messages without need to
351       specify the SMTP server and others each time. If you need to send only
352       one mail using MailMsg() or MailFile() you do not have to create a
353       named object and then call the method. You may do it like this :
354
355        (new Mail::Sender)->MailMsg({smtp => 'mail.company.com', ...});
356
357       Returns ref to the Mail::Sender object if successfull.
358
359       MailFile
360
361        MailFile([from [, replyto [, to [, smtp [, subject [, headers]]]]]], message, file(s))
362        MailFile({[from => "somebody@somewhere.com"]
363                  [, to => "else@nowhere.com"] [...],
364                  msg => "Message", file => "File"})
365
366       Sends one or more files by mail. If a mail in $sender is opened it gets
367       closed and a new mail is created and sent. $sender is then closed.  If
368       some parameters are unspecified or empty, it uses the parameters passed
369       to the ""$Sender=new Mail::Sender(...)"";
370
371       The "file" parameter may be a "filename", a "list, of, file, names" or
372       a \@list_of_file_names.
373
374       see "new Mail::Sender" for info about the parameters.
375
376       Just keep in mind that parameters like ctype, charset and encoding will
377       be used for the attached file, not the body of the message.  If you
378       want to specify those parameters for the body you have to use b_ctype,
379       b_charset and b_encoding. Sorry.
380
381       Returns ref to the Mail::Sender object if successfull.
382
383       Send
384
385        Send(@strings)
386
387       Prints the strings to the socket. Doesn't add any end-of-line charac‐
388       ters.  Doesn't encode the data! You should use "\r\n" as the
389       end-of-line!
390
391       UNLESS YOU ARE ABSOLUTELY SURE YOU KNOW WHAT YOU ARE DOING YOU SHOULD
392       USE SendEnc() INSTEAD!
393
394       Returns the object if successfull.
395
396       SendLine
397
398        SendLine(@strings)
399
400       Prints the strings to the socket. Adds the end-of-line character at the
401       end.  Doesn't encode the data! You should use "\r\n" as the
402       end-of-line!
403
404       UNLESS YOU ARE ABSOLUTELY SURE YOU KNOW WHAT YOU ARE DOING YOU SHOULD
405       USE SendLineEnc() INSTEAD!
406
407       Returns the object if successfull.
408
409       print
410
411       Alias to SendEnc().
412
413       Keep in mind that you can't write :
414
415               print $sender "...";
416
417       you have to use
418
419               $sender->print("...");
420
421       If you want to be able to print into the message as if it was a normal
422       file handle take a look at "GetHandle"()
423
424       SendEnc
425
426        SendEnc(@strings)
427
428       Prints the strings to the socket. Doesn't add any end-of-line charac‐
429       ters.
430
431       Encodes the text using the selected encoding (none/Base64/Quoted-print‐
432       able)
433
434       Returns the object if successfull.
435
436       SendLineEnc
437
438        SendLineEnc(@strings)
439
440       Prints the strings to the socket and adds the end-of-line character at
441       the end.  Encodes the text using the selected encoding
442       (none/Base64/Quoted-printable).
443
444       Do NOT mix up /Send(Line)?(Ex)?/ and /Send(Line)?Enc/! SendEnc does
445       some buffering necessary for correct Base64 encoding, and /Send(Ex)?/
446       is not aware of that!
447
448       Usage of /Send(Line)?(Ex)?/ in non xBIT parts not recommended.  Using
449       "Send(encode_base64($string))" may work, but more likely it will not!
450       In particular if you use several such to create one part, the data is
451       very likely to get crippled.
452
453       Returns the object if successfull.
454
455       SendEx
456
457        SendEx(@strings)
458
459       Prints the strings to the socket. Doesn't add any end-of-line charac‐
460       ters.  Changes all end-of-lines to "\r\n". Doesn't encode the data!
461
462       UNLESS YOU ARE ABSOLUTELY SURE YOU KNOW WHAT YOU ARE DOING YOU SHOULD
463       USE SendEnc() INSTEAD!
464
465       Returns the object if successfull.
466
467       SendLineEx
468
469        SendLineEx(@strings)
470
471       Prints the strings to the socket. Adds an end-of-line character at the
472       end.  Changes all end-of-lines to "\r\n". Doesn't encode the data!
473
474       UNLESS YOU ARE ABSOLUTELY SURE YOU KNOW WHAT YOU ARE DOING YOU SHOULD
475       USE SendEnc() INSTEAD!
476
477       Returns the object if successfull.
478
479       Part
480
481        Part( I<description>, I<ctype>, I<encoding>, I<disposition> [, I<content_id> [, I<msg>]]);
482        Part( {[description => "desc"], [ctype => "content-type"], [encoding => "..."],
483            [disposition => "..."], [content_id => "..."], [msg => ...]});
484
485       Prints a part header for the multipart message and (if specified) the
486       contents.  The undefined or empty variables are ignored.
487
488       description
489         The title for this part.
490
491       ctype
492         the content type (MIME type) of this part. May contain some other
493         parameters, such as charset or name.
494
495         Defaults to "application/octet-stream".
496
497         Since 0.8.00 you may use even "multipart/..." types. Such a multipart
498         part should be closed by a call to $sender->EndPart($ctype).
499
500                 ...
501                 $sender->Part({ctype => "multipart/related", ...});
502                         $sender->Part({ctype => 'text/html', ...});
503                         $sender->Attach({file => 'some_image.gif', content_id => 'foo', ...});
504                 $sender->EndPart("multipart/related");
505                 ...
506
507         Please see the examples below.
508
509       encoding
510         the encoding used for this part of message. Eg. Base64, Uuencode,
511         7BIT ...
512
513         Defaults to "7BIT".
514
515       disposition
516         This parts disposition. Eg: 'attachment; filename="send.pl"'.
517
518         Defaults to "attachment". If you specify "none" or "", the Con‐
519         tent-disposition: line will not be included in the headers.
520
521       content_id
522         The content id of the part, used in multipart/related.  If not speci‐
523         fied, the header is not included.
524
525       msg
526         The content of the part. You do not have to specify the content here,
527         you may use SendEnc() to add content to the part.
528
529       charset
530         The charset of the part.
531
532       Returns the Mail::Sender object if successfull, negative error code if
533       not.
534
535       Body
536
537        Body([charset [, encoding [, content-type]]]);
538        Body({charset => '...', encoding => '...', ctype => '...', msg => '...');
539
540       Sends the head of the multipart message body. You can specify the
541       charset and the encoding. Default is "US-ASCII","7BIT",'text/plain'.
542
543       If you pass undef or zero as the parameter, this function uses the
544       default value:
545
546           Body(0,0,'text/html');
547
548       Returns the Mail::Sender object if successfull, negative error code if
549       not.
550
551       SendFile
552
553       Alias to Attach()
554
555       Attach
556
557        Attach( I<description>, I<ctype>, I<encoding>, I<disposition>, I<file>);
558        Attach( { [description => "desc"] , [ctype => "ctype"], [encoding => "encoding"],
559                    [disposition => "disposition"], file => "file"});
560
561        Sends a file as a separate part of the mail message. Only in multipart mode.
562
563       description
564         The title for this part.
565
566       ctype
567         the content type (MIME type) of this part. May contain some other
568         parameters, such as charset or name.
569
570         Defaults to "application/octet-stream".
571
572       encoding
573         the encoding used for this part of message. Eg. Base64, Uuencode,
574         7BIT ...
575
576         Defaults to "Base64".
577
578       disposition
579         This parts disposition. Eg: 'attachment; filename="send.pl"'. If you
580         use 'attachment; filename=*' the * will be replaced by the respective
581         names of the sent files.
582
583         Defaults to "attachment; filename=*". If you do not want to include
584         this header use "" as the value.
585
586       file
587         The name of the file to send or a 'list, of, names' or a ['refer‐
588         ence','to','a','list','of','filenames']. Each file will be sent as a
589         separate part.
590
591         Please keep in mind that if you pass a string as this parameter the
592         module will split it on commas! If your filenames may contain commas
593         and you want to be sure they are sent correctly you have to use the
594         reference to array format:
595
596                 file => [ $filename],
597
598       content_id
599         The content id of the message part. Used in multipart/related.
600
601          Special values:
602           "*" => the name of the file
603           "#" => autoincremented number (starting from 0)
604
605       Returns the Mail::Sender object if successfull, negative error code if
606       not.
607
608       EndPart
609
610        $sender->EndPart($ctype);
611
612       Closes a multipart part.
613
614       If the $ctype is not present or evaluates to false, only the current
615       SIMPLE part is closed!  Don't do that unless you are really sure you
616       know what you are doing.
617
618       It's best to always pass to the ->EndPart() the content type of the
619       corresponding ->Part().
620
621       Close
622
623        $sender->Close;
624        $sender->Close(1);
625
626       Close and send the email message. If you pass a true value to the
627       method the connection will be closed even if the "keepconnection" was
628       specified. You should only keep the connection open if you plan to send
629       another message immediately. And you should not keep it open for hun‐
630       dreds of emails even if you do send them all in a row.
631
632       This method should be called automatically when destructing the object,
633       but you should not rely on it. If you want to be sure your message WAS
634       processed by the SMTP server you SHOULD call Close() explicitely.
635
636       Returns the Mail::Sender object if successfull, negative error code if
637       not, zero if $sender was not connected at all.  The zero usualy means
638       that the Open/OpenMultipart failed and you did not test its return
639       value.
640
641       Cancel
642
643        $sender->Cancel;
644
645       Cancel an opened message.
646
647       SendFile and other methods may set $sender->{'error'}.  In that case
648       "undef $sender" calls "$sender-">Cancel not "$sender-">Close!!!
649
650       Returns the Mail::Sender object if successfull, negative error code if
651       not.
652
653       QueryAuthProtocols
654
655               @protocols = $sender->QueryAuthProtocols();
656               @protocols = $sender->QueryAuthProtocols( $smtpserver);
657
658       Queryies the server (specified either in the default options for
659       Mail::Sender, the "new Mail::Sender" command or as a parameter to this
660       method for the authentication protocols it supports.
661
662       GetHandle
663
664       Returns a "filehandle" to which you can print the message or file to
665       attach or whatever.  The data you print to this handle will be encoded
666       as necessary. Closing this handle closes either the message (for single
667       part messages) or the part.
668
669               $sender->Open({...});
670               my $handle = $sender->GetHandle();
671               print $handle "Hello world.\n"
672               my ($mday,$mon,$year) = (localtime())[3,4,5];
673               printf $handle "Today is %04d/%02d/%02d.", $year+1900, $mon+1, $mday;
674               close $handle;
675
676       P.S.: There is a big difference between the handle stored in
677       $sender->{'socket'} and the handle returned by this function ! If you
678       print something to $sender->{'socket'} it will be sent to the server
679       without any modifications, encoding, escaping, ...  You should NOT
680       touch the $sender->{'socket'} unless you really really know what you
681       are doing.
682

FUNCTIONS

684       GuessCType
685
686               $ctype = GuessCType $filename, $filepath;
687
688       Guesses the content type based on the filename or the file contents.
689       This function is used when you attach a file and do not specify the
690       content type.  It is not exported by default!
691
692       The builtin version uses the filename extension to guess the type.
693       Currently there are only a few extensions defined, you may add other
694       extensions this way:
695
696               $Mail::Sender::CTypes{'EXT'} = 'content/type';
697               ...
698
699       The extension has to be in UPPERCASE and will be matched case sensi‐
700       tively.
701
702       The package now includes two addins improving the guesswork. If you
703       "use" one of them in your script, it replaces the builtin GuessCType()
704       subroutine with a better one:
705
706               Mail::Sender::CType::Win32
707                       Win32 only, the content type is read from the registry
708               Mail::Sender::CType::Ext
709                       any OS, a longer list of extensions from A. Guillaume
710

CONFIG

712       If you create a file named Sender.config in the same directory where
713       Sender.pm resides, this file will be "require"d as soon as you "use
714       Mail::Sender" in your script. Of course the Sender.config MUST "return
715       a true value", that is it has to be succesfully compiled and the last
716       statement must return a true value. You may use this to forbide the use
717       of Mail::Sender to some users.
718
719       You may define the default settings for new Mail::Sender objects and do
720       a few more things.
721
722       The default options are stored in hash %Mail::Sender::default. You may
723       use all the options you'd use in "new", "Open", "OpenMultipart",
724       "MailMsg" or "MailFile".
725
726        Eg.
727         %default = (
728           smtp => 'mail.yourhost.cz',
729           from => getlogin.'yourhost.cz',
730           client => getlogin.'.yourhost.cz'
731         );
732         # of course you will use your own mail server here !
733
734       The other options you may set here (or later of course) are
735       $Mail::Sender::SITE_HEADERS, $Mail::Sender::NO_X_MAILER and
736       $Mail::Sender::NO_DATE. (These are plain old scalar variables, there is
737       no function or method for modifying them. Just set them to anything you
738       need.)
739
740       The $Mail::Sender::SITE_HEADERS may contain headers that will be added
741       to each mail message sent by this script, the
742       $Mail::Sender::NO_X_MAILER disables the header item specifying that the
743       message was sent by Mail::Sender and $Mail::Sender::NO_DATE turns off
744       the Date: header generation.
745
746       !!! $Mail::Sender::SITE_HEADERS may NEVER end with \r\n !!!
747
748       If you want to set the $Mail::Sender::SITE_HEADERS for every script
749       sent from your server without your users being able to change it you
750       may use this hack:
751
752        $loginname = something_that_identifies_the_user();
753        *Mail::Sender::SITE_HEADERS = \"X-Sender: $loginname via $0";
754        $Mail::Sender::NO_X_MAILER = 1;
755
756       You may even "install" your custom function that will be evaluated for
757       each message just before contacting the server. You may change all the
758       options from within as well as stop sending the message.
759
760       All you have to do is to create a function named SiteHook in
761       Mail::Sender package. This function will get the Mail::Sender object as
762       its first argument. If it returns a TRUE value the message is sent, if
763       it returns FALSE the sending is canceled and the user gets "Site spe‐
764       cific error" error message.
765
766       If you want to give some better error message you may do it like this :
767
768        sub SiteHook {
769         my $self = shift;
770         if (whatever($self)) {
771           $self->Error( SITEERROR);
772           $Mail::Sender::Error = "I don't like this mail";
773           return 0
774         } else {
775           return 1;
776         }
777        }
778
779       This example will ensure the from address is the users real address :
780
781        sub SiteHook {
782         my $self = shift;
783         $self->{'fromaddr'} = getlogin.'@yoursite.com';
784         $self->{'from'} = getlogin.'@yoursite.com';
785         1;
786        }
787
788       Please note that at this stage the from address is in two different
789       object properties.
790
791       $self->{'from'} is the address as it will appear in the mail, that is
792       it may include the full name of the user or any other comment ( "Jan
793       Krynicky <jenda@krynicky.cz>" for example), while the $self->{'fro‐
794       maddr'} is realy just the email address per se and it will be used in
795       conversation with the SMTP server. It must be without comments
796       ("jenda@krynicky.cz" for example)!
797
798       Without write access to .../lib/Mail/Sender.pm or
799       .../lib/Mail/Sender.config your users will then be unable to get rid of
800       this header. Well ... everything is doable, if they are cheeky enough
801       ... :-(
802
803       So if you take care of some site with virtual servers for several
804       clients and implement some policy via SiteHook() or
805       $Mail::Sender::SITE_HEADERS search the clients' scripts for "SiteHook"
806       and "SITE_HEADERS" from time to time. To see who's cheating.
807

AUTHENTICATION

809       If you get a "Local user "xxx@yyy.com" unknown on host "zzz"" message
810       it usualy means that your mail server is set up to forbid mail relay.
811       That is it only accepts messages to or from a local user.  If you need
812       to be able to send a message with both the sender's and recipient's
813       address remote, you need to somehow authenticate to the server. You may
814       need the help of the mail server's administrator to find out what user‐
815       name and password and/or what authentication protocol are you supposed
816       to use.
817
818       There are many authentication protocols defined for ESTMP, Mail::Sender
819       natively supports only PLAIN, LOGIN, CRAM-MD5 and NTLM (please see the
820       docs for "new Mail::Sender").
821
822       If you want to know what protocols are supported by your server you may
823       get the list by this:
824
825               /tmp# perl -MMail::Sender -e 'Mail::Sender->printAuthProtocols("the.server.com")'
826         or
827               c:\> perl -MMail::Sender -e "Mail::Sender->printAuthProtocols('the.server.com')"
828
829       There is one more way to authenticate. Some servers want you to login
830       by POP3 before you can send a message. You have to use Net::POP3 or
831       Mail::POP3Client to do this.
832
833       Other protocols
834
835       It is possible to add new authentication protocols to Mail::Sender. All
836       you have to do is to define a function Mail::Sender::Auth::PROTO‐
837       COL_NAME that will implement the login. The function gets one parameter
838       ... the Mail::Sender object.  It can access these properties:
839
840               $obj->{'socket'} : the socket to print to and read from
841                       you may use the send_cmd() function to send a request
842                       and read a response from the server
843               $obj->{'authid'} : the username specified in the new Mail::Sender,
844                       Open or OpenMultipart call
845               $obj->{'authid'} : the password
846               $obj->{auth...} : all unknown parameters passed to the constructor or the mail
847                       opening/creation methods are preserved in the object. If the protocol requires
848                       any other options, please use names starting with "auth". Eg. "authdomain", ...
849               $obj->{'error'} : this should be set to a negative error number. Please use numbers
850                       below -1000 for custom errors.
851               $obj->{'error_msg'} : this should be set to the error message
852
853               If the login fails you should
854                       1) Set $Mail::Sender::Error to the error message
855                       2) Set $obj->{'error_msg'} to the error message
856                       2) Set $obj->{'error'} to a negative number
857                       3) return a negative number
858               If it succeeds, please return "nothing" :
859                       return;
860
861       Please use the protocols defined within Sender.pm as examples.
862

EXAMPLES

864       Object creation
865
866        ref ($sender = new Mail::Sender { from => 'somebody@somewhere.com',
867              smtp => 'mail.yourISP.com', boundary => 'This-is-a-mail-boundary-435427'})
868        or die "Error in mailing : $Mail::Sender::Error\n";
869
870       or
871
872        my $sender = new Mail::Sender { ... };
873        die "Error in mailing : $Mail::Sender::Error\n" unless ref $sender;
874
875       or
876
877        my $sender = new Mail::Sender { ..., on_errors => 'undef' }
878          or die "Error in mailing : $Mail::Sender::Error\n";
879
880       You may specify the options either when creating the Mail::Sender
881       object or later when you open a message. You may also set the default
882       options when installing the module (See "CONFIG" section). This way the
883       admin may set the SMTP server and even the authentication options and
884       the users do not have to specify it again.
885
886       You should keep in mind that the way Mail::Sender reports failures
887       depends on the 'on_errors'=> option. If you set it to 'die' it throws
888       an exception, if you set it to "undef" or 'undef' it returns undef and
889       otherwise it returns a negative error code!
890
891       Simple single part message
892
893               $sender = new Mail::Sender {
894                       smtp => 'mail.yourISP.com',
895                       from => 'somebody@somewhere.com',
896                       on_errors => undef,
897               }
898                       or die "Can't create the Mail::Sender object: $Mail::Sender::Error\n";
899               $sender->Open({
900                       to => 'mama@home.org, papa@work.com',
901                       cc => 'somebody@somewhere.com',
902                       subject => 'Sorry, I\'ll come later.'
903               })
904                       or die "Can't open the message: $sender->{'error_msg'}\n";
905               $sender->SendLineEnc("I'm sorry, but thanks to the lusers,
906                       I'll come at 10pm at best.");
907               $sender->SendLineEnc("\nHi, Jenda");
908               $sender->Close()
909                       or die "Failed to send the message: $sender->{'error_msg'}\n";
910
911       or
912
913               eval {
914                       $sender = new Mail::Sender {
915                               smtp => 'mail.yourISP.com',
916                               from => 'somebody@somewhere.com',
917                               on_errors => 'die',
918                       };
919                       $sender->Open({
920                               to => 'mama@home.org, papa@work.com',
921                               cc => 'somebody@somewhere.com',
922                               subject => 'Sorry, I\'ll come later.'
923                       });
924                       $sender->SendLineEnc("I'm sorry, but thanks to the lusers,
925                               I'll come at 10pm at best.");
926                       $sender->SendLineEnc("\nHi, Jenda");
927                       $sender->Close();
928               };
929               if ($@) {
930                       die "Failed to send the message: $@\n";
931               }
932
933       or
934
935               $sender = new Mail::Sender {
936                       smtp => 'mail.yourISP.com',
937                       from => 'somebody@somewhere.com',
938                       on_errors => 'code',
939               };
940               die "Can't create the Mail::Sender object: $Mail::Sender::Error\n"
941                       unless ref $sender;
942               ref $sender->Open({
943                       to => 'mama@home.org, papa@work.com',
944                       cc => 'somebody@somewhere.com',
945                       subject => 'Sorry, I\'ll come later.'
946               })
947                       or die "Can't open the message: $sender->{'error_msg'}\n";
948               $sender->SendLineEnc("I'm sorry, but thanks to the lusers,
949                       I'll come at 10pm at best.");
950               $sender->SendLineEnc("\nHi, Jenda");
951               ref $sender->Close
952                       or die "Failed to send the message: $sender->{'error_msg'}\n";
953
954       Using GetHandle()
955
956         ref $sender->Open({to => 'friend@other.com', subject => 'Hello dear friend'})
957                or die "Error: $Mail::Sender::Error\n";
958         my $FH = $sender->GetHandle();
959         print $FH "How are you?\n\n";
960         print $FH <<'*END*';
961         I've found these jokes.
962
963          Doctor, I feel like a pack of cards.
964          Sit down and I'll deal with you later.
965
966          Doctor, I keep thinking I'm a dustbin.
967          Don't talk rubbish.
968
969         Hope you like'em. Jenda
970         *END*
971
972         $sender->Close;
973         # or
974         # close $FH;
975
976       or
977
978         eval {
979           $sender->Open({ on_errors => 'die',
980                                to => 'mama@home.org, papa@work.com',
981                       cc => 'somebody@somewhere.com',
982                       subject => 'Sorry, I\'ll come later.'});
983           $sender->SendLineEnc("I'm sorry, but due to a big load of work,
984         I'll come at 10pm at best.");
985           $sender->SendLineEnc("\nHi, Jenda");
986           $sender->Close;
987         };
988         if ($@) {
989           print "Error sending the email: $@\n";
990         } else {
991           print "The mail was sent.\n";
992         }
993
994       Multipart message with attachment
995
996        $sender->OpenMultipart({to => 'Perl-Win32-Users@activeware.foo',
997                                subject => 'Mail::Sender.pm - new module'});
998        $sender->Body;
999        $sender->SendEnc(<<'*END*');
1000        Here is a new module Mail::Sender.
1001        It provides an object based interface to sending SMTP mails.
1002        It uses a direct socket connection, so it doesn't need any
1003        additional program.
1004
1005        Enjoy, Jenda
1006        *END*
1007        $sender->Attach(
1008         {description => 'Perl module Mail::Sender.pm',
1009          ctype => 'application/x-zip-encoded',
1010          encoding => 'Base64',
1011          disposition => 'attachment; filename="Sender.zip"; type="ZIP archive"',
1012          file => 'sender.zip'
1013         });
1014        $sender->Close;
1015
1016       or
1017
1018        $sender->OpenMultipart({to => 'Perl-Win32-Users@activeware.foo',
1019                                subject => 'Mail::Sender.pm - new version'});
1020        $sender->Body({ msg => <<'*END*' });
1021        Here is a new module Mail::Sender.
1022        It provides an object based interface to sending SMTP mails.
1023        It uses a direct socket connection, so it doesn't need any
1024        additional program.
1025
1026        Enjoy, Jenda
1027        *END*
1028        $sender->Attach(
1029         {description => 'Perl module Mail::Sender.pm',
1030          ctype => 'application/x-zip-encoded',
1031          encoding => 'Base64',
1032          disposition => 'attachment; filename="Sender.zip"; type="ZIP archive"',
1033          file => 'sender.zip'
1034         });
1035        $sender->Close;
1036
1037       or (in case you have the file contents in a scalar)
1038
1039        $sender->OpenMultipart({to => 'Perl-Win32-Users@activeware.foo',
1040                                subject => 'Mail::Sender.pm - new version'});
1041        $sender->Body({ msg => <<'*END*' });
1042        Here is a new module Mail::Sender.
1043        It provides an object based interface to sending SMTP mails.
1044        It uses a direct socket connection, so it doesn't need any
1045        additional program.
1046
1047        Enjoy, Jenda
1048        *END*
1049        $sender->Part(
1050         {description => 'Perl module Mail::Sender.pm',
1051          ctype => 'application/x-zip-encoded',
1052          encoding => 'Base64',
1053          disposition => 'attachment; filename="Sender.zip"; type="ZIP archive"',
1054          msg => $sender_zip_contents,
1055         });
1056        $sender->Close;
1057
1058       Using exceptions (no need to test return values after each function)
1059
1060        use Mail::Sender;
1061        eval {
1062        (new Mail::Sender {on_errors => 'die'})
1063               ->OpenMultipart({smtp=> 'jenda.krynicky.cz', to => 'jenda@krynicky.cz',subject => 'Mail::Sender.pm - new version'})
1064               ->Body({ msg => <<'*END*' })
1065        Here is a new module Mail::Sender.
1066        It provides an object based interface to sending SMTP mails.
1067        It uses a direct socket connection, so it doesn't need any
1068        additional program.
1069
1070        Enjoy, Jenda
1071        *END*
1072               ->Attach({
1073                       description => 'Perl module Mail::Sender.pm',
1074                       ctype => 'application/x-zip-encoded',
1075                       encoding => 'Base64',
1076                       disposition => 'attachment; filename="Sender.zip"; type="ZIP archive"',
1077                       file => 'W:\jenda\packages\Mail\Sender\Mail-Sender-0.7.14.3.tar.gz'
1078               })
1079               ->Close();
1080        } or print "Error sending mail: $@\n";
1081
1082       Using MailMsg() shortcut to send simple messages
1083
1084       If everything you need is to send a simple message you may use:
1085
1086        if (ref ($sender->MailMsg({to =>'Jenda@Krynicky.czX', subject => 'this is a test',
1087                                msg => "Hi Johnie.\nHow are you?"}))) {
1088         print "Mail sent OK."
1089        } else {
1090         die "$Mail::Sender::Error\n";
1091        }
1092
1093       or
1094
1095        if ($sender->MailMsg({
1096          smtp => 'mail.yourISP.com',
1097          from => 'somebody@somewhere.com',
1098          to =>'Jenda@Krynicky.czX',
1099          subject => 'this is a test',
1100          msg => "Hi Johnie.\nHow are you?"
1101        }) < 0) {
1102         die "$Mail::Sender::Error\n";
1103        }
1104        print "Mail sent OK."
1105
1106       Using MailMsg and authentication
1107
1108        if ($sender->MailMsg({
1109          smtp => 'mail.yourISP.com',
1110          from => 'somebody@somewhere.com',
1111          to =>'Jenda@Krynicky.czX',
1112          subject => 'this is a test',
1113          msg => "Hi Johnie.\nHow are you?"
1114          auth => 'NTLM',
1115          authid => 'jenda',
1116          authpwd => 'benda',
1117        }) < 0) {
1118         die "$Mail::Sender::Error\n";
1119        }
1120        print "Mail sent OK."
1121
1122       Using MailFile() shortcut to send an attachment
1123
1124       If you want to attach some files:
1125
1126        (ref ($sender->MailFile(
1127         {to =>'you@address.com', subject => 'this is a test',
1128          msg => "Hi Johnie.\nI'm sending you the pictures you wanted.",
1129          file => 'image1.jpg,image2.jpg'
1130         }))
1131         and print "Mail sent OK."
1132        )
1133        or die "$Mail::Sender::Error\n";
1134
1135       Sending HTML messages
1136
1137       If you are sure the HTML doesn't contain any accentuated characters
1138       (with codes above 127).
1139
1140        open IN, $htmlfile or die "Cannot open $htmlfile : $!\n";
1141        $sender->Open({ from => 'your@address.com', to => 'other@address.com',
1142               subject => 'HTML test',
1143               ctype => "text/html",
1144               encoding => "7bit"
1145        }) or die $Mail::Sender::Error,"\n";
1146
1147        while (<IN>) { $sender->SendEx($_) };
1148        close IN;
1149        $sender->Close();
1150
1151       Otherwise use SendEnc() instead of SendEx() and "quoted-printable"
1152       instead of "7bit".
1153
1154       Another ... quicker way ... would be:
1155
1156        open IN, $htmlfile or die "Cannot open $htmlfile : $!\n";
1157        $sender->Open({ from => 'your@address.com', to => 'other@address.com',
1158               subject => 'HTML test',
1159               ctype => "text/html",
1160               encoding => "quoted-printable"
1161        }) or die $Mail::Sender::Error,"\n";
1162
1163        while (read IN, $buff, 4096) { $sender->SendEnc($buff) };
1164        close IN;
1165        $sender->Close();
1166
1167       Sending HTML messages with inline images
1168
1169               if (ref $sender->OpenMultipart({
1170                       from => 'someone@somewhere.net', to => $recipients,
1171                       subject => 'Embedded Image Test',
1172                       boundary => 'boundary-test-1',
1173                       multipart => 'related'})) {
1174                       $sender->Attach(
1175                                {description => 'html body',
1176                                ctype => 'text/html; charset=us-ascii',
1177                                encoding => '7bit',
1178                                disposition => 'NONE',
1179                                file => 'test.html'
1180                       });
1181                       $sender->Attach({
1182                               description => 'ed\'s gif',
1183                               ctype => 'image/gif',
1184                               encoding => 'base64',
1185                               disposition => "inline; filename=\"apache_pb.gif\";\r\nContent-ID: <img1>",
1186                               file => 'apache_pb.gif'
1187                       });
1188                       $sender->Close() or die "Close failed! $Mail::Sender::Error\n";
1189               } else {
1190                       die "Cannot send mail: $Mail::Sender::Error\n";
1191               }
1192
1193       And in the HTML you'll have this :
1194        ... <IMG src="cid:img1"> ...  on the place where you want the inlined
1195       image.
1196
1197       Please keep in mind that the image name is unimportant, it's the Con‐
1198       tent-ID what counts!
1199
1200       # or using the eval{ $obj->Method()->Method()->...->Close()} trick ...
1201
1202               use Mail::Sender;
1203               eval {
1204               (new Mail::Sender)
1205                       ->OpenMultipart({
1206                               to => 'someone@somewhere.com',
1207                               subject => 'Embedded Image Test',
1208                               boundary => 'boundary-test-1',
1209                               type => 'multipart/related'
1210                       })
1211                       ->Attach({
1212                               description => 'html body',
1213                               ctype => 'text/html; charset=us-ascii',
1214                               encoding => '7bit',
1215                               disposition => 'NONE',
1216                               file => 'c:\temp\zk\HTMLTest.htm'
1217                       })
1218                       ->Attach({
1219                               description => 'Test gif',
1220                               ctype => 'image/gif',
1221                               encoding => 'base64',
1222                               disposition => "inline; filename=\"test.gif\";\r\nContent-ID: <img1>",
1223                               file => 'test.gif'
1224                       })
1225                       ->Close()
1226               }
1227               or die "Cannot send mail: $Mail::Sender::Error\n";
1228
1229       Sending message with plaintext and HTML alternatives
1230
1231               use Mail::Sender;
1232
1233               eval {
1234                       (new Mail::Sender)
1235                       ->OpenMultipart({
1236                               to => 'someone@somewhere.com',
1237                               subject => 'Alternatives',
1238               #               debug => 'c:\temp\zkMailFlow.log',
1239                               multipart => 'mixed',
1240                       })
1241                               ->Part({ctype => 'multipart/alternative'})
1242                                       ->Part({ ctype => 'text/plain', disposition => 'NONE', msg => <<'*END*' })
1243               A long
1244               mail
1245               message.
1246               *END*
1247                                       ->Part({ctype => 'text/html', disposition => 'NONE', msg => <<'*END*'})
1248               <html><body><h1>A long</h1><p align=center>
1249               mail
1250               message.
1251               </p></body></html>
1252               *END*
1253                               ->EndPart("multipart/alternative")
1254                       ->Close();
1255               } or print "Error sending mail: $Mail::Sender::Error\n";
1256
1257       Sending message with plaintext and HTML alternatives with inline images
1258
1259               use Mail::Sender;
1260
1261               eval {
1262                       (new Mail::Sender)
1263                       ->OpenMultipart({
1264                               to => 'someone@somewhere.com',
1265                               subject => 'Alternatives with images',
1266               #               debug => 'c:\temp\zkMailFlow.log',
1267                               multipart => 'related',
1268                       })
1269                               ->Part({ctype => 'multipart/alternative'})
1270                                       ->Part({ ctype => 'text/plain', disposition => 'NONE', msg => <<'*END*' })
1271               A long
1272               mail
1273               message.
1274               *END*
1275                                       ->Part({ctype => 'text/html', disposition => 'NONE', msg => <<'*END*'})
1276               <html><body><h1>A long</h1><p align=center>
1277               mail
1278               message.
1279               <img src="cid:img1">
1280               </p></body></html>
1281               *END*
1282                               ->EndPart("multipart/alternative")
1283                               ->Attach({
1284                                       description => 'ed\'s jpg',
1285                                       ctype => 'image/jpeg',
1286                                       encoding => 'base64',
1287                                       disposition => "inline; filename=\"0518m_b.jpg\";\r\nContent-ID: <img1>",
1288                                       file => 'E:\pix\humor\0518m_b.jpg'
1289                               })
1290                       ->Close();
1291               } or print "Error sending mail: $Mail::Sender::Error\n";
1292
1293       Keep in mind please that different mail clients display messages dif‐
1294       ferently. You may need to try several ways to create messages so that
1295       they appear the way you need.  These two examples looked like I
1296       expected in Pegasus Email and MS Outlook.
1297
1298       If this doesn't work with your mail client, please let me know and we
1299       might find a way.
1300
1301       Sending a file that was just uploaded from an HTML form
1302
1303        use CGI;
1304        use Mail::Sender;
1305
1306        $query = new CGI;
1307
1308        # uploading the file...
1309        $filename = $query->param('mailformFile');
1310        if ($filename ne ""){
1311         $tmp_file = $query->tmpFileName($filename);
1312        }
1313
1314        $sender = new Mail::Sender {from => 'script@krynicky.cz',smtp => 'mail.krynicky.czX'};
1315        $sender->OpenMultipart({to=> 'jenda@krynicky.czX',subject=> 'test CGI attach'});
1316        $sender->Body();
1317        $sender->Send(<<"*END*");
1318        This is just a test of mail with an uploaded file.
1319
1320        Jenda
1321        *END*
1322        $sender->Attach({
1323           encoding => 'Base64',
1324           description => $filename,
1325           ctype => $query->uploadInfo($filename)->{'Content-Type'},
1326           disposition => "attachment; filename = $filename",
1327           file => $tmp_file
1328        });
1329        $sender->Close();
1330
1331        print "Content-type: text/plain\n\nYes, it's sent\n\n";
1332
1333       Listing the authentication protocols supported by the server
1334
1335        use Mail::Sender;
1336        my $sender = new Mail::Sender {smtp => 'localhost'};
1337        die "Error: $Mail::Sender::Error\n" unless ref $sender;
1338        print join(', ', $sender->QueryAuthProtocols()),"\n";
1339
1340       or (if you have Mail::Sender 0.8.05 or newer)
1341
1342        use Mail::Sender;
1343        print join(', ', Mail::Sender->QueryAuthProtocols('localhost')),"\n";
1344
1345       or
1346
1347        use Mail::Sender;
1348        print join(', ', Mail::Sender::QueryAuthProtocols('localhost')),"\n";
1349
1350       FAQ
1351
1352       Forwarding the messages created by Mail::Sender removes accents. Why?
1353
1354       The most likely colprit is missing or incorrect charset specified for
1355       the body or a part of the email. You should add something like
1356
1357               charset => 'iso-8859-1',
1358               encoding => 'quoted-printable',
1359
1360       to the parameters passed to Open(), OpenMultipart(), MailMsg(), Body()
1361       or Part() or
1362
1363               b_charset => 'iso-8859-1',
1364               b_encoding => 'quoted-printable',
1365
1366       to the parameters for MailFile().
1367
1368       If you use a different charset ('iso-8859-2', 'win-1250', ...) you will
1369       of course need to specify that charset. If you are not sure, try to
1370       send a mail with some other mail client and then look at the mes‐
1371       sage/part headers.
1372
1373       Sometimes there is an equals sign at the end of an attached file when I
1374       open the email in Outlook. What's wrong?
1375
1376       Outlook is. It has (had) a bug in its quoted printable decoding rou‐
1377       tines.  This problem happens only in quoted-printable encoded parts on
1378       multipart messages.  And only if the data in that part do not end with
1379       a newline. (This is new in 0.8.08, in older versions it happened in all
1380       QP encoded parts.)
1381
1382       The problem is that an equals sign at the end of a line in a quoted
1383       printable encoded text means "ignore the newline". That is
1384
1385               fooo sdfg sdfg sdfh dfh =
1386               dfsgdsfg
1387
1388       should be decoded as
1389
1390               fooo sdfg sdfg sdfh dfh dfsgdsfg
1391
1392       The problem is at the very end of a file. The part boundary (text sepa‐
1393       rating different parts of a multipart message) has to start on a new
1394       line, if the attached file ends by a newline everything is cool.  If it
1395       doesn't I need to add a newline and to denote that the newline is not
1396       part of the original file I add an equals:
1397
1398               dfgd dsfgh dfh dfh dfhdfhdfhdfgh
1399               this is the last line.=
1400               --message-boundary-146464--
1401
1402       Otherwise I'd add a newline at the end of the file.  If you do not care
1403       about the newline and want to be sure Outlook doesn't add the equals to
1404       the file add
1405
1406               bypass_outlook_bug => 1
1407
1408       parameter to "new Mail::Sender" or "Open"/"OpenMultipart".
1409
1410       WARNING
1411
1412       DO NOT mix Open(Multipart)⎪Send(Line)(Ex)⎪Close with MailMsg or Mail‐
1413       File.  Both Mail(Msg/File) close any Open-ed mail.  Do not try this:
1414
1415        $sender = new Mail::Sender ...;
1416        $sender->OpenMultipart...;
1417        $sender->Body;
1418        $sender->Send("...");
1419        $sender->MailFile({file => 'something.ext');
1420        $sender->Close;
1421
1422       This WON'T work!!!
1423
1424       GOTCHAS
1425
1426       Local user "someone@somewhere.com" doesn't exist
1427
1428       "Thanks" to spammers mail servers usualy do not allow just anyone to
1429       post a message through them.  Most often they require that either the
1430       sender or the recipient is local to the server
1431
1432       Mail::Sendmail works, Mail::Sender doesn't
1433
1434       If you are able to connect to the mail server and scripts using
1435       Mail::Sendmail work, but Mail::Sender fails with "connect() failed",
1436       please review the settings in /etc/services. The port for SMTP should
1437       be 25.
1438
1439       $/ and $\
1440
1441       If you change the $/ ($RS, $INPUT_RECORD_SEPARATOR) or $\ ($ORS, $OUT‐
1442       PUT_RECORD_SEPARATOR) or $, ($OFS, $OUTPUT_FIELD_SEPARATOR)
1443       Mail::Sender may stop working! Keep in mind that those variables are
1444       global and therefore they change the behaviour of <> and print every‐
1445       where.  And since the SMTP is a plain text protocol if you change the
1446       notion of lines you can break it.
1447
1448       If you have to fiddle with $/, $\ or $, do it in the smallest possible
1449       block of code and local()ize the change!
1450
1451               open my $IN, '<', $filename or die "Can't open $filename: $!\n";
1452               my $data = do {local $/; <$IN>};
1453               close $IN;
1454

BUGS

1456       I'm sure there are many. Please let me know if you find any.
1457
1458       The problem with multiline responses from some SMTP servers (namely
1459       qmail) is solved. At last.
1460

SEE ALSO

1462       MIME::Lite, MIME::Entity, Mail::Sendmail, Mail::Mailer, ...
1463
1464       There are lots of mail related modules on CPAN, with different capabil‐
1465       ities and interfaces. You have to find the right one yourself :-)
1466

DISCLAIMER

1468       This module is based on SendMail.pm Version : 1.21 that appeared in
1469       Perl-Win32-Users@activeware.com mailing list. I don't remember the name
1470       of the poster and it's not mentioned in the script. Thank you mr.
1471       "undef".
1472

AUTHOR

1474       Jan Krynicky <Jenda@Krynicky.cz> http://Jenda.Krynicky.cz
1475
1476       With help of Rodrigo Siqueira <rodrigo@insite.com.br>, Ed McGuigan
1477       <itstech1@gate.net>, John Sanche <john@quadrant.net>, Brian Blakley
1478       <bblakley@mp5.net>, and others.
1479

COPYRIGHT

1481       Copyright (c) 1997-2006 Jan Krynicky <Jenda@Krynicky.cz>. All rights
1482       reserved.
1483
1484       This program is free software; you can redistribute it and/or modify it
1485       under the same terms as Perl itself. There is only one aditional condi‐
1486       tion, you may NOT use this module for SPAMing! NEVER! (see
1487       http://spam.abuse.net/ for definition)
1488
1489
1490
1491perl v5.8.8                       2006-02-25                         Sender(3)