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