cpan/libnet/lib/Net/SMTP.pm

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