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