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.07";
  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 Attempt SASL authentication. Requires Authen::SASL module.
 837
 838 =item mail ( ADDRESS [, OPTIONS] )
 839
 840 =item send ( ADDRESS )
 841
 842 =item send_or_mail ( ADDRESS )
 843
 844 =item send_and_mail ( ADDRESS )
 845
 846 Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<ADDRESS>
 847 is the address of the sender. This initiates the sending of a message. The
 848 method C<recipient> should be called for each address that the message is to
 849 be sent to.
 850
 851 The C<mail> method can some additional ESMTP OPTIONS which is passed
 852 in hash like fashion, using key and value pairs.  Possible options are:
 853
 854  Size        => <bytes>
 855  Return      => "FULL" | "HDRS"
 856  Bits        => "7" | "8" | "binary"
 857  Transaction => <ADDRESS>
 858  Envelope    => <ENVID>     # xtext-encodes its argument
 859  ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
 860  XVERP       => 1
 861  AUTH        => <submitter> # encoded address according to RFC 2554
 862
 863 The C<Return> and C<Envelope> parameters are used for DSN (Delivery
 864 Status Notification).
 865
 866 The submitter address in C<AUTH> option is expected to be in a format as
 867 required by RFC 2554, in an RFC2821-quoted form and xtext-encoded, or <> .
 868
 869 =item reset ()
 870
 871 Reset the status of the server. This may be called after a message has been
 872 initiated, but before any data has been sent, to cancel the sending of the
 873 message.
 874
 875 =item recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )
 876
 877 Notify the server that the current message should be sent to all of the
 878 addresses given. Each address is sent as a separate command to the server.
 879 Should the sending of any address result in a failure then the process is
 880 aborted and a I<false> value is returned. It is up to the user to call
 881 C<reset> if they so desire.
 882
 883 The C<recipient> method can also pass additional case-sensitive OPTIONS as an
 884 anonymous hash using key and value pairs.  Possible options are:
 885
 886   Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
 887   ORcpt   => <ORCPT>
 888   SkipBad => 1        (to ignore bad addresses)
 889
 890 If C<SkipBad> is true the C<recipient> will not return an error when a bad
 891 address is encountered and it will return an array of addresses that did
 892 succeed.
 893
 894   $smtp->recipient($recipient1,$recipient2);  # Good
 895   $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
 896   $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
 897   @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
 898   $smtp->recipient("$recipient,$recipient2"); # BAD
 899
 900 Notify is used to request Delivery Status Notifications (DSNs), but your
 901 SMTP/ESMTP service may not respect this request depending upon its version and
 902 your site's SMTP configuration.
 903
 904 Leaving out the Notify option usually defaults an SMTP service to its default
 905 behavior equivalent to ['FAILURE'] notifications only, but again this may be
 906 dependent upon your site's SMTP configuration.
 907
 908 The NEVER keyword must appear by itself if used within the Notify option and "requests
 909 that a DSN not be returned to the sender under any conditions."
 910
 911   {Notify => ['NEVER']}
 912
 913   $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good
 914
 915 You may use any combination of these three values 'SUCCESS','FAILURE','DELAY' in
 916 the anonymous array reference as defined by RFC3461 (see http://www.ietf.org/rfc/rfc3461.txt
 917 for more information.  Note: quotations in this topic from same.).
 918
 919 A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on
 920 successful delivery or delivery failure, respectively."
 921
 922 A Notify parameter of 'DELAY' "indicates the sender's willingness to receive
 923 delayed DSNs.  Delayed DSNs may be issued if delivery of a message has been
 924 delayed for an unusual amount of time (as determined by the Message Transfer
 925 Agent (MTA) at which the message is delayed), but the final delivery status
 926 (whether successful or failure) cannot be determined.  The absence of the DELAY
 927 keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under
 928 any conditions."
 929
 930   {Notify => ['SUCCESS','FAILURE','DELAY']}
 931
 932   $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
 933
 934 ORcpt is also part of the SMTP DSN extension according to RFC3461.
 935 It is used to pass along the original recipient that the mail was first
 936 sent to.  The machine that generates a DSN will use this address to inform
 937 the sender, because he can't know if recipients get rewritten by mail servers.
 938 It is expected to be in a format as required by RFC3461, xtext-encoded.
 939
 940 =item to ( ADDRESS [, ADDRESS [...]] )
 941
 942 =item cc ( ADDRESS [, ADDRESS [...]] )
 943
 944 =item bcc ( ADDRESS [, ADDRESS [...]] )
 945
 946 Synonyms for C<recipient>.
 947
 948 =item data ( [ DATA ] )
 949
 950 Initiate the sending of the data from the current message.
 951
 952 C<DATA> may be a reference to a list or a list and must be encoded by the
 953 caller to octets of whatever encoding is required, e.g. by using the Encode
 954 module's C<encode()> function.
 955
 956 If specified the contents of C<DATA> and a termination string C<".\r\n"> is
 957 sent to the server. The result will be true if the data was accepted.
 958
 959 If C<DATA> is not specified then the result will indicate that the server
 960 wishes the data to be sent. The data must then be sent using the C<datasend>
 961 and C<dataend> methods described in L<Net::Cmd>.
 962
 963 =item bdat ( DATA )
 964
 965 =item bdatlast ( DATA )
 966
 967 Use the alternate DATA command "BDAT" of the data chunking service extension
 968 defined in RFC1830 for efficiently sending large MIME messages.
 969
 970 =item expand ( ADDRESS )
 971
 972 Request the server to expand the given address Returns an array
 973 which contains the text read from the server.
 974
 975 =item verify ( ADDRESS )
 976
 977 Verify that C<ADDRESS> is a legitimate mailing address.
 978
 979 Most sites usually disable this feature in their SMTP service configuration.
 980 Use "Debug => 1" option under new() to see if disabled.
 981
 982 =item help ( [ $subject ] )
 983
 984 Request help text from the server. Returns the text or undef upon failure
 985
 986 =item quit ()
 987
 988 Send the QUIT command to the remote SMTP server and close the socket connection.
 989
 990 =item can_inet6 ()
 991
 992 Returns whether we can use IPv6.
 993
 994 =item can_ssl ()
 995
 996 Returns whether we can use SSL.
 997
 998 =back
 999
1000 =head1 ADDRESSES
1001
1002 Net::SMTP attempts to DWIM with addresses that are passed. For
1003 example an application might extract The From: line from an email
1004 and pass that to mail(). While this may work, it is not recommended.
1005 The application should really use a module like L<Mail::Address>
1006 to extract the mail address and pass that.
1007
1008 If C<ExactAddresses> is passed to the constructor, then addresses
1009 should be a valid rfc2821-quoted address, although Net::SMTP will
1010 accept the address surrounded by angle brackets.
1011
1012  funny user@domain      WRONG
1013  "funny user"@domain    RIGHT, recommended
1014  <"funny user"@domain>  OK
1015
1016 =head1 SEE ALSO
1017
1018 L<Net::Cmd>,
1019 L<IO::Socket::SSL>
1020
1021 =head1 AUTHOR
1022
1023 Graham Barr E<lt>F<gbarr@pobox.com>E<gt>
1024
1025 Steve Hay E<lt>F<shay@cpan.org>E<gt> is now maintaining libnet as of version
1026 1.22_02
1027
1028 =head1 COPYRIGHT
1029
1030 Versions up to 2.31_1 Copyright (c) 1995-2004 Graham Barr. All rights reserved.
1031 Changes in Version 2.31_2 onwards Copyright (C) 2013-2015 Steve Hay.  All rights
1032 reserved.
1033
1034 This module is free software; you can redistribute it and/or modify it under the
1035 same terms as Perl itself, i.e. under the terms of either the GNU General Public
1036 License or the Artistic License, as specified in the F<LICENCE> file.
1037
1038 =cut