This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade libnet from version 1.24 to 1.25
[perl5.git] / cpan / libnet / Net / SMTP.pm
1 # Net::SMTP.pm
2 #
3 # Copyright (c) 1995-2004 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
6
7 package Net::SMTP;
8
9 require 5.001;
10
11 use strict;
12 use vars qw($VERSION @ISA);
13 use Socket 1.3;
14 use Carp;
15 use IO::Socket;
16 use Net::Cmd;
17 use Net::Config;
18
19 $VERSION = "2.33";
20
21 @ISA = qw(Net::Cmd IO::Socket::INET);
22
23
24 sub new {
25   my $self = shift;
26   my $type = ref($self) || $self;
27   my ($host, %arg);
28   if (@_ % 2) {
29     $host = shift;
30     %arg  = @_;
31   }
32   else {
33     %arg  = @_;
34     $host = delete $arg{Host};
35   }
36   my $hosts = defined $host ? $host : $NetConfig{smtp_hosts};
37   my $obj;
38
39   my $h;
40   foreach $h (@{ref($hosts) ? $hosts : [$hosts]}) {
41     $obj = $type->SUPER::new(
42       PeerAddr => ($host = $h),
43       PeerPort => $arg{Port} || 'smtp(25)',
44       LocalAddr => $arg{LocalAddr},
45       LocalPort => $arg{LocalPort},
46       Proto     => 'tcp',
47       Timeout   => defined $arg{Timeout}
48       ? $arg{Timeout}
49       : 120
50       )
51       and last;
52   }
53
54   return undef
55     unless defined $obj;
56
57   $obj->autoflush(1);
58
59   $obj->debug(exists $arg{Debug} ? $arg{Debug} : undef);
60
61   unless ($obj->response() == CMD_OK) {
62     my $err = ref($obj) . ": " . $obj->code . " " . $obj->message;
63     $obj->close();
64     $@ = $err;
65     return undef;
66   }
67
68   ${*$obj}{'net_smtp_exact_addr'} = $arg{ExactAddresses};
69   ${*$obj}{'net_smtp_host'}       = $host;
70
71   (${*$obj}{'net_smtp_banner'}) = $obj->message;
72   (${*$obj}{'net_smtp_domain'}) = $obj->message =~ /\A\s*(\S+)/;
73
74   unless ($obj->hello($arg{Hello} || "")) {
75     my $err = ref($obj) . ": " . $obj->code . " " . $obj->message;
76     $obj->close();
77     $@ = $err;
78     return undef;
79   }
80
81   $obj;
82 }
83
84
85 sub host {
86   my $me = shift;
87   ${*$me}{'net_smtp_host'};
88 }
89
90 ##
91 ## User interface methods
92 ##
93
94
95 sub banner {
96   my $me = shift;
97
98   return ${*$me}{'net_smtp_banner'} || undef;
99 }
100
101
102 sub domain {
103   my $me = shift;
104
105   return ${*$me}{'net_smtp_domain'} || undef;
106 }
107
108
109 sub etrn {
110   my $self = shift;
111   defined($self->supports('ETRN', 500, ["Command unknown: 'ETRN'"]))
112     && $self->_ETRN(@_);
113 }
114
115
116 sub auth {
117   my ($self, $username, $password) = @_;
118
119   eval {
120     require MIME::Base64;
121     require Authen::SASL;
122   } or $self->set_status(500, ["Need MIME::Base64 and Authen::SASL todo auth"]), return 0;
123
124   my $mechanisms = $self->supports('AUTH', 500, ["Command unknown: 'AUTH'"]);
125   return unless defined $mechanisms;
126
127   my $sasl;
128
129   if (ref($username) and UNIVERSAL::isa($username, 'Authen::SASL')) {
130     $sasl = $username;
131     $sasl->mechanism($mechanisms);
132   }
133   else {
134     die "auth(username, password)" if not length $username;
135     $sasl = Authen::SASL->new(
136       mechanism => $mechanisms,
137       callback  => {
138         user     => $username,
139         pass     => $password,
140         authname => $username,
141       }
142     );
143   }
144
145   # We should probably allow the user to pass the host, but I don't
146   # currently know and SASL mechanisms that are used by smtp that need it
147   my $client = $sasl->client_new('smtp', ${*$self}{'net_smtp_host'}, 0);
148   my $str    = $client->client_start;
149
150   # We don't support sasl mechanisms that encrypt the socket traffic.
151   # todo that we would really need to change the ISA hierarchy
152   # so we don't inherit from IO::Socket, but instead hold it in an attribute
153
154   my @cmd = ("AUTH", $client->mechanism);
155   my $code;
156
157   push @cmd, MIME::Base64::encode_base64($str, '')
158     if defined $str and length $str;
159
160   while (($code = $self->command(@cmd)->response()) == CMD_MORE) {
161     @cmd = (
162       MIME::Base64::encode_base64(
163         $client->client_step(MIME::Base64::decode_base64(($self->message)[0])), ''
164       )
165     );
166   }
167
168   $code == CMD_OK;
169 }
170
171
172 sub hello {
173   my $me     = shift;
174   my $domain = shift || "localhost.localdomain";
175   my $ok     = $me->_EHLO($domain);
176   my @msg    = $me->message;
177
178   if ($ok) {
179     my $h = ${*$me}{'net_smtp_esmtp'} = {};
180     my $ln;
181     foreach $ln (@msg) {
182       $h->{uc $1} = $2
183         if $ln =~ /([-\w]+)\b[= \t]*([^\n]*)/;
184     }
185   }
186   elsif ($me->status == CMD_ERROR) {
187     @msg = $me->message
188       if $ok = $me->_HELO($domain);
189   }
190
191   return undef unless $ok;
192
193   $msg[0] =~ /\A\s*(\S+)/;
194   return ($1 || " ");
195 }
196
197
198 sub supports {
199   my $self = shift;
200   my $cmd  = uc shift;
201   return ${*$self}{'net_smtp_esmtp'}->{$cmd}
202     if exists ${*$self}{'net_smtp_esmtp'}->{$cmd};
203   $self->set_status(@_)
204     if @_;
205   return;
206 }
207
208
209 sub _addr {
210   my $self = shift;
211   my $addr = shift;
212   $addr = "" unless defined $addr;
213
214   if (${*$self}{'net_smtp_exact_addr'}) {
215     return $1 if $addr =~ /^\s*(<.*>)\s*$/s;
216   }
217   else {
218     return $1 if $addr =~ /(<[^>]*>)/;
219     $addr =~ s/^\s+|\s+$//sg;
220   }
221
222   "<$addr>";
223 }
224
225
226 sub mail {
227   my $me   = shift;
228   my $addr = _addr($me, shift);
229   my $opts = "";
230
231   if (@_) {
232     my %opt = @_;
233     my ($k, $v);
234
235     if (exists ${*$me}{'net_smtp_esmtp'}) {
236       my $esmtp = ${*$me}{'net_smtp_esmtp'};
237
238       if (defined($v = delete $opt{Size})) {
239         if (exists $esmtp->{SIZE}) {
240           $opts .= sprintf " SIZE=%d", $v + 0;
241         }
242         else {
243           carp 'Net::SMTP::mail: SIZE option not supported by host';
244         }
245       }
246
247       if (defined($v = delete $opt{Return})) {
248         if (exists $esmtp->{DSN}) {
249           $opts .= " RET=" . ((uc($v) eq "FULL") ? "FULL" : "HDRS");
250         }
251         else {
252           carp 'Net::SMTP::mail: DSN option not supported by host';
253         }
254       }
255
256       if (defined($v = delete $opt{Bits})) {
257         if ($v eq "8") {
258           if (exists $esmtp->{'8BITMIME'}) {
259             $opts .= " BODY=8BITMIME";
260           }
261           else {
262             carp 'Net::SMTP::mail: 8BITMIME option not supported by host';
263           }
264         }
265         elsif ($v eq "binary") {
266           if (exists $esmtp->{'BINARYMIME'} && exists $esmtp->{'CHUNKING'}) {
267             $opts .= " BODY=BINARYMIME";
268             ${*$me}{'net_smtp_chunking'} = 1;
269           }
270           else {
271             carp 'Net::SMTP::mail: BINARYMIME option not supported by host';
272           }
273         }
274         elsif (exists $esmtp->{'8BITMIME'} or exists $esmtp->{'BINARYMIME'}) {
275           $opts .= " BODY=7BIT";
276         }
277         else {
278           carp 'Net::SMTP::mail: 8BITMIME and BINARYMIME options not supported by host';
279         }
280       }
281
282       if (defined($v = delete $opt{Transaction})) {
283         if (exists $esmtp->{CHECKPOINT}) {
284           $opts .= " TRANSID=" . _addr($me, $v);
285         }
286         else {
287           carp 'Net::SMTP::mail: CHECKPOINT option not supported by host';
288         }
289       }
290
291       if (defined($v = delete $opt{Envelope})) {
292         if (exists $esmtp->{DSN}) {
293           $v =~ s/([^\041-\176]|=|\+)/sprintf "+%02X", ord($1)/sge;
294           $opts .= " ENVID=$v";
295         }
296         else {
297           carp 'Net::SMTP::mail: DSN option not supported by host';
298         }
299       }
300
301       if (defined($v = delete $opt{ENVID})) {
302
303         # expected to be in a format as required by RFC 3461, xtext-encoded
304         if (exists $esmtp->{DSN}) {
305           $opts .= " ENVID=$v";
306         }
307         else {
308           carp 'Net::SMTP::mail: DSN option not supported by host';
309         }
310       }
311
312       if (defined($v = delete $opt{AUTH})) {
313
314         # expected to be in a format as required by RFC 2554,
315         # rfc2821-quoted and xtext-encoded, or <>
316         if (exists $esmtp->{AUTH}) {
317           $v = '<>' if !defined($v) || $v eq '';
318           $opts .= " AUTH=$v";
319         }
320         else {
321           carp 'Net::SMTP::mail: AUTH option not supported by host';
322         }
323       }
324
325       if (defined($v = delete $opt{XVERP})) {
326         if (exists $esmtp->{'XVERP'}) {
327           $opts .= " XVERP";
328         }
329         else {
330           carp 'Net::SMTP::mail: XVERP option not supported by host';
331         }
332       }
333
334       carp 'Net::SMTP::recipient: unknown option(s) ' . join(" ", keys %opt) . ' - ignored'
335         if scalar keys %opt;
336     }
337     else {
338       carp 'Net::SMTP::mail: ESMTP not supported by host - options discarded :-(';
339     }
340   }
341
342   $me->_MAIL("FROM:" . $addr . $opts);
343 }
344
345
346 sub send          { my $me = shift; $me->_SEND("FROM:" . _addr($me, $_[0])) }
347 sub send_or_mail  { my $me = shift; $me->_SOML("FROM:" . _addr($me, $_[0])) }
348 sub send_and_mail { my $me = shift; $me->_SAML("FROM:" . _addr($me, $_[0])) }
349
350
351 sub reset {
352   my $me = shift;
353
354   $me->dataend()
355     if (exists ${*$me}{'net_smtp_lastch'});
356
357   $me->_RSET();
358 }
359
360
361 sub recipient {
362   my $smtp     = shift;
363   my $opts     = "";
364   my $skip_bad = 0;
365
366   if (@_ && ref($_[-1])) {
367     my %opt = %{pop(@_)};
368     my $v;
369
370     $skip_bad = delete $opt{'SkipBad'};
371
372     if (exists ${*$smtp}{'net_smtp_esmtp'}) {
373       my $esmtp = ${*$smtp}{'net_smtp_esmtp'};
374
375       if (defined($v = delete $opt{Notify})) {
376         if (exists $esmtp->{DSN}) {
377           $opts .= " NOTIFY=" . join(",", map { uc $_ } @$v);
378         }
379         else {
380           carp 'Net::SMTP::recipient: DSN option not supported by host';
381         }
382       }
383
384       if (defined($v = delete $opt{ORcpt})) {
385         if (exists $esmtp->{DSN}) {
386           $opts .= " ORCPT=" . $v;
387         }
388         else {
389           carp 'Net::SMTP::recipient: DSN option not supported by host';
390         }
391       }
392
393       carp 'Net::SMTP::recipient: unknown option(s) ' . join(" ", keys %opt) . ' - ignored'
394         if scalar keys %opt;
395     }
396     elsif (%opt) {
397       carp 'Net::SMTP::recipient: ESMTP not supported by host - options discarded :-(';
398     }
399   }
400
401   my @ok;
402   my $addr;
403   foreach $addr (@_) {
404     if ($smtp->_RCPT("TO:" . _addr($smtp, $addr) . $opts)) {
405       push(@ok, $addr) if $skip_bad;
406     }
407     elsif (!$skip_bad) {
408       return 0;
409     }
410   }
411
412   return $skip_bad ? @ok : 1;
413 }
414
415 BEGIN {
416   *to  = \&recipient;
417   *cc  = \&recipient;
418   *bcc = \&recipient;
419 }
420
421
422 sub data {
423   my $me = shift;
424
425   if (exists ${*$me}{'net_smtp_chunking'}) {
426     carp 'Net::SMTP::data: CHUNKING extension in use, must call bdat instead';
427   }
428   else {
429     my $ok = $me->_DATA() && $me->datasend(@_);
430
431     $ok && @_
432       ? $me->dataend
433       : $ok;
434   }
435 }
436
437
438 sub bdat {
439   my $me = shift;
440
441   if (exists ${*$me}{'net_smtp_chunking'}) {
442     my $data = shift;
443
444     $me->_BDAT(length $data)
445       && $me->rawdatasend($data)
446       && $me->response() == CMD_OK;
447   }
448   else {
449     carp 'Net::SMTP::bdat: CHUNKING extension is not in use, call data instead';
450   }
451 }
452
453
454 sub bdatlast {
455   my $me = shift;
456
457   if (exists ${*$me}{'net_smtp_chunking'}) {
458     my $data = shift;
459
460     $me->_BDAT(length $data, "LAST")
461       && $me->rawdatasend($data)
462       && $me->response() == CMD_OK;
463   }
464   else {
465     carp 'Net::SMTP::bdat: CHUNKING extension is not in use, call data instead';
466   }
467 }
468
469
470 sub datafh {
471   my $me = shift;
472   return unless $me->_DATA();
473   return $me->tied_fh;
474 }
475
476
477 sub expand {
478   my $me = shift;
479
480   $me->_EXPN(@_)
481     ? ($me->message)
482     : ();
483 }
484
485
486 sub verify { shift->_VRFY(@_) }
487
488
489 sub help {
490   my $me = shift;
491
492   $me->_HELP(@_)
493     ? scalar $me->message
494     : undef;
495 }
496
497
498 sub quit {
499   my $me = shift;
500
501   $me->_QUIT;
502   $me->close;
503 }
504
505
506 sub DESTROY {
507
508   # ignore
509 }
510
511 ##
512 ## RFC821 commands
513 ##
514
515
516 sub _EHLO { shift->command("EHLO", @_)->response() == CMD_OK }
517 sub _HELO { shift->command("HELO", @_)->response() == CMD_OK }
518 sub _MAIL { shift->command("MAIL", @_)->response() == CMD_OK }
519 sub _RCPT { shift->command("RCPT", @_)->response() == CMD_OK }
520 sub _SEND { shift->command("SEND", @_)->response() == CMD_OK }
521 sub _SAML { shift->command("SAML", @_)->response() == CMD_OK }
522 sub _SOML { shift->command("SOML", @_)->response() == CMD_OK }
523 sub _VRFY { shift->command("VRFY", @_)->response() == CMD_OK }
524 sub _EXPN { shift->command("EXPN", @_)->response() == CMD_OK }
525 sub _HELP { shift->command("HELP", @_)->response() == CMD_OK }
526 sub _RSET { shift->command("RSET")->response() == CMD_OK }
527 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
528 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
529 sub _DATA { shift->command("DATA")->response() == CMD_MORE }
530 sub _BDAT { shift->command("BDAT", @_) }
531 sub _TURN { shift->unsupported(@_); }
532 sub _ETRN { shift->command("ETRN", @_)->response() == CMD_OK }
533 sub _AUTH { shift->command("AUTH", @_)->response() == CMD_OK }
534
535 1;
536
537 __END__
538
539 =head1 NAME
540
541 Net::SMTP - Simple Mail Transfer Protocol Client
542
543 =head1 SYNOPSIS
544
545     use Net::SMTP;
546
547     # Constructors
548     $smtp = Net::SMTP->new('mailhost');
549     $smtp = Net::SMTP->new('mailhost', Timeout => 60);
550
551 =head1 DESCRIPTION
552
553 This module implements a client interface to the SMTP and ESMTP
554 protocol, enabling a perl5 application to talk to SMTP servers. This
555 documentation assumes that you are familiar with the concepts of the
556 SMTP protocol described in RFC821.
557
558 A new Net::SMTP object must be created with the I<new> method. Once
559 this has been done, all SMTP commands are accessed through this object.
560
561 The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
562
563 =head1 EXAMPLES
564
565 This example prints the mail domain name of the SMTP server known as mailhost:
566
567     #!/usr/local/bin/perl -w
568
569     use Net::SMTP;
570
571     $smtp = Net::SMTP->new('mailhost');
572     print $smtp->domain,"\n";
573     $smtp->quit;
574
575 This example sends a small message to the postmaster at the SMTP server
576 known as mailhost:
577
578     #!/usr/local/bin/perl -w
579
580     use Net::SMTP;
581
582     my $smtp = Net::SMTP->new('mailhost');
583
584     $smtp->mail($ENV{USER});
585     if ($smtp->to('postmaster')) {
586      $smtp->data();
587      $smtp->datasend("To: postmaster\n");
588      $smtp->datasend("\n");
589      $smtp->datasend("A simple test message\n");
590      $smtp->dataend();
591     } else {
592      print "Error: ", $smtp->message();
593     }
594
595     $smtp->quit;
596
597 =head1 CONSTRUCTOR
598
599 =over 4
600
601 =item new ( [ HOST ] [, OPTIONS ] )
602
603 This is the constructor for a new Net::SMTP object. C<HOST> is the
604 name of the remote host to which an SMTP connection is required.
605
606 On failure C<undef> will be returned and C<$@> will contain the reason
607 for the failure.
608
609 C<HOST> is optional. If C<HOST> is not given then it may instead be
610 passed as the C<Host> option described below. If neither is given then
611 the C<SMTP_Hosts> specified in C<Net::Config> will be used.
612
613 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
614 Possible options are:
615
616 B<Hello> - SMTP requires that you identify yourself. This option
617 specifies a string to pass as your mail domain. If not given localhost.localdomain
618 will be used.
619
620 B<Host> - SMTP host to connect to. It may be a single scalar (hostname[:port]),
621 as defined for the C<PeerAddr> option in L<IO::Socket::INET>, or a reference to
622 an array with hosts to try in turn. The L</host> method will return the value
623 which was used to connect to the host.
624
625 B<Port> - port to connect to. Format - C<PeerHost> from L<IO::Socket::INET> new method.
626 Default - 25.
627
628 B<LocalAddr> and B<LocalPort> - These parameters are passed directly
629 to IO::Socket to allow binding the socket to a local port.
630
631 B<Timeout> - Maximum time, in seconds, to wait for a response from the
632 SMTP server (default: 120)
633
634 B<ExactAddresses> - If true the all ADDRESS arguments must be as
635 defined by C<addr-spec> in RFC2822. If not given, or false, then
636 Net::SMTP will attempt to extract the address from the value passed.
637
638 B<Debug> - Enable debugging information
639
640
641 Example:
642
643
644     $smtp = Net::SMTP->new('mailhost',
645                            Hello => 'my.mail.domain',
646                            Timeout => 30,
647                            Debug   => 1,
648                           );
649
650     # the same
651     $smtp = Net::SMTP->new(
652                            Host => 'mailhost',
653                            Hello => 'my.mail.domain',
654                            Timeout => 30,
655                            Debug   => 1,
656                           );
657
658     # Connect to the default server from Net::config
659     $smtp = Net::SMTP->new(
660                            Hello => 'my.mail.domain',
661                            Timeout => 30,
662                           );
663
664 =back
665
666 =head1 METHODS
667
668 Unless otherwise stated all methods return either a I<true> or I<false>
669 value, with I<true> meaning that the operation was a success. When a method
670 states that it returns a value, failure will be returned as I<undef> or an
671 empty list.
672
673 C<Net::SMTP> inherits from C<Net::Cmd> so methods defined in C<Net::Cmd> may
674 be used to send commands to the remote SMTP server in addition to the methods
675 documented here.
676
677 =over 4
678
679 =item banner ()
680
681 Returns the banner message which the server replied with when the
682 initial connection was made.
683
684 =item domain ()
685
686 Returns the domain that the remote SMTP server identified itself as during
687 connection.
688
689 =item hello ( DOMAIN )
690
691 Tell the remote server the mail domain which you are in using the EHLO
692 command (or HELO if EHLO fails).  Since this method is invoked
693 automatically when the Net::SMTP object is constructed the user should
694 normally not have to call it manually.
695
696 =item host ()
697
698 Returns the value used by the constructor, and passed to IO::Socket::INET,
699 to connect to the host.
700
701 =item etrn ( DOMAIN )
702
703 Request a queue run for the DOMAIN given.
704
705 =item auth ( USERNAME, PASSWORD )
706
707 Attempt SASL authentication. Requires Authen::SASL module.
708
709 =item mail ( ADDRESS [, OPTIONS] )
710
711 =item send ( ADDRESS )
712
713 =item send_or_mail ( ADDRESS )
714
715 =item send_and_mail ( ADDRESS )
716
717 Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<ADDRESS>
718 is the address of the sender. This initiates the sending of a message. The
719 method C<recipient> should be called for each address that the message is to
720 be sent to.
721
722 The C<mail> method can some additional ESMTP OPTIONS which is passed
723 in hash like fashion, using key and value pairs.  Possible options are:
724
725  Size        => <bytes>
726  Return      => "FULL" | "HDRS"
727  Bits        => "7" | "8" | "binary"
728  Transaction => <ADDRESS>
729  Envelope    => <ENVID>     # xtext-encodes its argument
730  ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
731  XVERP       => 1
732  AUTH        => <submitter> # encoded address according to RFC 2554
733
734 The C<Return> and C<Envelope> parameters are used for DSN (Delivery
735 Status Notification).
736
737 The submitter address in C<AUTH> option is expected to be in a format as
738 required by RFC 2554, in an RFC2821-quoted form and xtext-encoded, or <> .
739
740 =item reset ()
741
742 Reset the status of the server. This may be called after a message has been 
743 initiated, but before any data has been sent, to cancel the sending of the
744 message.
745
746 =item recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )
747
748 Notify the server that the current message should be sent to all of the
749 addresses given. Each address is sent as a separate command to the server.
750 Should the sending of any address result in a failure then the process is
751 aborted and a I<false> value is returned. It is up to the user to call
752 C<reset> if they so desire.
753
754 The C<recipient> method can also pass additional case-sensitive OPTIONS as an
755 anonymous hash using key and value pairs.  Possible options are:
756
757   Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
758   ORcpt   => <ORCPT>
759   SkipBad => 1        (to ignore bad addresses)
760
761 If C<SkipBad> is true the C<recipient> will not return an error when a bad
762 address is encountered and it will return an array of addresses that did
763 succeed.
764
765   $smtp->recipient($recipient1,$recipient2);  # Good
766   $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
767   $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
768   @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
769   $smtp->recipient("$recipient,$recipient2"); # BAD
770
771 Notify is used to request Delivery Status Notifications (DSNs), but your
772 SMTP/ESMTP service may not respect this request depending upon its version and
773 your site's SMTP configuration.
774
775 Leaving out the Notify option usually defaults an SMTP service to its default
776 behavior equivalent to ['FAILURE'] notifications only, but again this may be
777 dependent upon your site's SMTP configuration.
778
779 The NEVER keyword must appear by itself if used within the Notify option and "requests
780 that a DSN not be returned to the sender under any conditions."
781
782   {Notify => ['NEVER']}
783
784   $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good
785
786 You may use any combination of these three values 'SUCCESS','FAILURE','DELAY' in
787 the anonymous array reference as defined by RFC3461 (see http://www.ietf.org/rfc/rfc3461.txt
788 for more information.  Note: quotations in this topic from same.).
789
790 A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on
791 successful delivery or delivery failure, respectively."
792
793 A Notify parameter of 'DELAY' "indicates the sender's willingness to receive
794 delayed DSNs.  Delayed DSNs may be issued if delivery of a message has been
795 delayed for an unusual amount of time (as determined by the Message Transfer
796 Agent (MTA) at which the message is delayed), but the final delivery status
797 (whether successful or failure) cannot be determined.  The absence of the DELAY
798 keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under
799 any conditions."
800
801   {Notify => ['SUCCESS','FAILURE','DELAY']}
802
803   $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
804
805 ORcpt is also part of the SMTP DSN extension according to RFC3461.
806 It is used to pass along the original recipient that the mail was first
807 sent to.  The machine that generates a DSN will use this address to inform
808 the sender, because he can't know if recipients get rewritten by mail servers.
809 It is expected to be in a format as required by RFC3461, xtext-encoded.
810
811 =item to ( ADDRESS [, ADDRESS [...]] )
812
813 =item cc ( ADDRESS [, ADDRESS [...]] )
814
815 =item bcc ( ADDRESS [, ADDRESS [...]] )
816
817 Synonyms for C<recipient>.
818
819 =item data ( [ DATA ] )
820
821 Initiate the sending of the data from the current message. 
822
823 C<DATA> may be a reference to a list or a list. If specified the contents
824 of C<DATA> and a termination string C<".\r\n"> is sent to the server. And the
825 result will be true if the data was accepted.
826
827 If C<DATA> is not specified then the result will indicate that the server
828 wishes the data to be sent. The data must then be sent using the C<datasend>
829 and C<dataend> methods described in L<Net::Cmd>.
830
831 =item expand ( ADDRESS )
832
833 Request the server to expand the given address Returns an array
834 which contains the text read from the server.
835
836 =item verify ( ADDRESS )
837
838 Verify that C<ADDRESS> is a legitimate mailing address.
839
840 Most sites usually disable this feature in their SMTP service configuration.
841 Use "Debug => 1" option under new() to see if disabled.
842
843 =item help ( [ $subject ] )
844
845 Request help text from the server. Returns the text or undef upon failure
846
847 =item quit ()
848
849 Send the QUIT command to the remote SMTP server and close the socket connection.
850
851 =back
852
853 =head1 ADDRESSES
854
855 Net::SMTP attempts to DWIM with addresses that are passed. For
856 example an application might extract The From: line from an email
857 and pass that to mail(). While this may work, it is not recommended.
858 The application should really use a module like L<Mail::Address>
859 to extract the mail address and pass that.
860
861 If C<ExactAddresses> is passed to the constructor, then addresses
862 should be a valid rfc2821-quoted address, although Net::SMTP will
863 accept the address surrounded by angle brackets.
864
865  funny user@domain      WRONG
866  "funny user"@domain    RIGHT, recommended
867  <"funny user"@domain>  OK
868
869 =head1 SEE ALSO
870
871 L<Net::Cmd>
872
873 =head1 AUTHOR
874
875 Graham Barr <gbarr@pobox.com>
876
877 =head1 COPYRIGHT
878
879 Copyright (c) 1995-2004 Graham Barr. All rights reserved.
880 This program is free software; you can redistribute it and/or modify
881 it under the same terms as Perl itself.
882
883 =cut