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