[ Index ]

PHP Cross Reference of Unnamed Project

title

Body

[close]

/se3-unattended/var/se3/unattended/install/linuxaux/opt/perl/lib/5.10.0/Net/ -> SMTP.pm (source)

   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


Generated: Tue Mar 17 22:47:18 2015 Cross-referenced by PHPXref 0.7.1