3 # Copyright (c) 1995-1997 Graham Barr <gbarr@pobox.com>. All rights reserved.
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
12 use vars qw($VERSION @ISA);
19 $VERSION = "2.15"; # $Id$
21 @ISA = qw(Net::Cmd IO::Socket::INET);
26 my $type = ref($self) || $self;
27 my $host = shift if @_ % 2;
29 my $hosts = defined $host ? [ $host ] : $NetConfig{smtp_hosts};
33 foreach $h (@{$hosts})
35 $obj = $type->SUPER::new(PeerAddr => ($host = $h),
36 PeerPort => $arg{Port} || 'smtp(25)',
38 Timeout => defined $arg{Timeout}
49 $obj->debug(exists $arg{Debug} ? $arg{Debug} : undef);
51 unless ($obj->response() == CMD_OK)
57 ${*$obj}{'net_smtp_host'} = $host;
59 (${*$obj}{'net_smtp_banner'}) = $obj->message;
60 (${*$obj}{'net_smtp_domain'}) = $obj->message =~ /\A\s*(\S+)/;
62 unless($obj->hello($arg{Hello} || ""))
72 ## User interface methods
79 return ${*$me}{'net_smtp_banner'} || undef;
86 return ${*$me}{'net_smtp_domain'} || undef;
91 defined($self->supports('ETRN',500,["Command unknown: 'ETRN'"])) &&
101 Net::Domain::hostfqdn();
104 my $ok = $me->_EHLO($domain);
105 my @msg = $me->message;
109 my $h = ${*$me}{'net_smtp_esmtp'} = {};
113 if $ln =~ /(\S+)\b[ \t]*([^\n]*)/;
116 elsif($me->status == CMD_ERROR)
119 if $ok = $me->_HELO($domain);
122 $ok && $msg[0] =~ /\A(\S+)/
130 return ${*$self}{'net_smtp_esmtp'}->{$cmd}
131 if exists ${*$self}{'net_smtp_esmtp'}->{$cmd};
132 $self->set_status(@_)
139 my $addr = shift || "";
142 if $addr =~ /(<[^>]+>)/so;
145 $addr =~ s/(\A\s+|\s+\Z)//sog;
147 return "<" . $addr . ">";
154 my $addr = _addr(shift);
162 if(exists ${*$me}{'net_smtp_esmtp'})
164 my $esmtp = ${*$me}{'net_smtp_esmtp'};
166 if(defined($v = delete $opt{Size}))
168 if(exists $esmtp->{SIZE})
170 $opts .= sprintf " SIZE=%d", $v + 0
174 carp 'Net::SMTP::mail: SIZE option not supported by host';
178 if(defined($v = delete $opt{Return}))
180 if(exists $esmtp->{DSN})
182 $opts .= " RET=" . uc $v
186 carp 'Net::SMTP::mail: DSN option not supported by host';
190 if(defined($v = delete $opt{Bits}))
192 if(exists $esmtp->{'8BITMIME'})
194 $opts .= $v == 8 ? " BODY=8BITMIME" : " BODY=7BIT"
198 carp 'Net::SMTP::mail: 8BITMIME option not supported by host';
202 if(defined($v = delete $opt{Transaction}))
204 if(exists $esmtp->{CHECKPOINT})
206 $opts .= " TRANSID=" . _addr($v);
210 carp 'Net::SMTP::mail: CHECKPOINT option not supported by host';
214 if(defined($v = delete $opt{Envelope}))
216 if(exists $esmtp->{DSN})
218 $v =~ s/([^\041-\176]|=|\+)/sprintf "+%02x", ord($1)/sge;
223 carp 'Net::SMTP::mail: DSN option not supported by host';
227 carp 'Net::SMTP::recipient: unknown option(s) '
228 . join(" ", keys %opt)
234 carp 'Net::SMTP::mail: ESMTP not supported by host - options discarded :-(';
238 $me->_MAIL("FROM:".$addr.$opts);
241 sub send { shift->_SEND("FROM:" . _addr($_[0])) }
242 sub send_or_mail { shift->_SOML("FROM:" . _addr($_[0])) }
243 sub send_and_mail { shift->_SAML("FROM:" . _addr($_[0])) }
250 if(exists ${*$me}{'net_smtp_lastch'});
262 if(@_ && ref($_[-1]))
264 my %opt = %{pop(@_)};
267 $skip_bad = delete $opt{'SkipBad'};
269 if(exists ${*$smtp}{'net_smtp_esmtp'})
271 my $esmtp = ${*$smtp}{'net_smtp_esmtp'};
273 if(defined($v = delete $opt{Notify}))
275 if(exists $esmtp->{DSN})
277 $opts .= " NOTIFY=" . join(",",map { uc $_ } @$v)
281 carp 'Net::SMTP::recipient: DSN option not supported by host';
285 carp 'Net::SMTP::recipient: unknown option(s) '
286 . join(" ", keys %opt)
292 carp 'Net::SMTP::recipient: ESMTP not supported by host - options discarded :-(';
300 if($smtp->_RCPT("TO:" . _addr($addr) . $opts)) {
301 push(@ok,$addr) if $skip_bad;
308 return $skip_bad ? @ok : 1;
311 sub to { shift->recipient(@_) }
317 my $ok = $me->_DATA() && $me->datasend(@_);
319 $ok && @_ ? $me->dataend
327 $me->_EXPN(@_) ? ($me->message)
332 sub verify { shift->_VRFY(@_) }
338 $me->_HELP(@_) ? scalar $me->message
359 sub _EHLO { shift->command("EHLO", @_)->response() == CMD_OK }
360 sub _HELO { shift->command("HELO", @_)->response() == CMD_OK }
361 sub _MAIL { shift->command("MAIL", @_)->response() == CMD_OK }
362 sub _RCPT { shift->command("RCPT", @_)->response() == CMD_OK }
363 sub _SEND { shift->command("SEND", @_)->response() == CMD_OK }
364 sub _SAML { shift->command("SAML", @_)->response() == CMD_OK }
365 sub _SOML { shift->command("SOML", @_)->response() == CMD_OK }
366 sub _VRFY { shift->command("VRFY", @_)->response() == CMD_OK }
367 sub _EXPN { shift->command("EXPN", @_)->response() == CMD_OK }
368 sub _HELP { shift->command("HELP", @_)->response() == CMD_OK }
369 sub _RSET { shift->command("RSET")->response() == CMD_OK }
370 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
371 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
372 sub _DATA { shift->command("DATA")->response() == CMD_MORE }
373 sub _TURN { shift->unsupported(@_); }
374 sub _ETRN { shift->command("ETRN", @_)->response() == CMD_OK }
382 Net::SMTP - Simple Mail Transfer Protocol Client
389 $smtp = Net::SMTP->new('mailhost');
390 $smtp = Net::SMTP->new('mailhost', Timeout => 60);
394 This module implements a client interface to the SMTP and ESMTP
395 protocol, enabling a perl5 application to talk to SMTP servers. This
396 documentation assumes that you are familiar with the concepts of the
397 SMTP protocol described in RFC821.
399 A new Net::SMTP object must be created with the I<new> method. Once
400 this has been done, all SMTP commands are accessed through this object.
402 The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
406 This example prints the mail domain name of the SMTP server known as mailhost:
408 #!/usr/local/bin/perl -w
412 $smtp = Net::SMTP->new('mailhost');
413 print $smtp->domain,"\n";
416 This example sends a small message to the postmaster at the SMTP server
419 #!/usr/local/bin/perl -w
423 $smtp = Net::SMTP->new('mailhost');
425 $smtp->mail($ENV{USER});
426 $smtp->to('postmaster');
429 $smtp->datasend("To: postmaster\n");
430 $smtp->datasend("\n");
431 $smtp->datasend("A simple test message\n");
440 =item new Net::SMTP [ HOST, ] [ OPTIONS ]
442 This is the constructor for a new Net::SMTP object. C<HOST> is the
443 name of the remote host to which a SMTP connection is required.
445 If C<HOST> is not given, then the C<SMTP_Host> specified in C<Net::Config>
448 C<OPTIONS> are passed in a hash like fashion, using key and value pairs.
449 Possible options are:
451 B<Hello> - SMTP requires that you identify yourself. This option
452 specifies a string to pass as your mail domain. If not
453 given a guess will be taken.
455 B<Timeout> - Maximum time, in seconds, to wait for a response from the
456 SMTP server (default: 120)
458 B<Debug> - Enable debugging information
464 $smtp = Net::SMTP->new('mailhost',
465 Hello => 'my.mail.domain'
472 Unless otherwise stated all methods return either a I<true> or I<false>
473 value, with I<true> meaning that the operation was a success. When a method
474 states that it returns a value, failure will be returned as I<undef> or an
481 Returns the banner message which the server replied with when the
482 initial connection was made.
486 Returns the domain that the remote SMTP server identified itself as during
489 =item hello ( DOMAIN )
491 Tell the remote server the mail domain which you are in using the EHLO
492 command (or HELO if EHLO fails). Since this method is invoked
493 automatically when the Net::SMTP object is constructed the user should
494 normally not have to call it manually.
496 =item etrn ( DOMAIN )
498 Request a queue run for the DOMAIN given.
500 =item mail ( ADDRESS [, OPTIONS] )
502 =item send ( ADDRESS )
504 =item send_or_mail ( ADDRESS )
506 =item send_and_mail ( ADDRESS )
508 Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<ADDRESS>
509 is the address of the sender. This initiates the sending of a message. The
510 method C<recipient> should be called for each address that the message is to
513 The C<mail> method can some additional ESMTP OPTIONS which is passed
514 in hash like fashion, using key and value pairs. Possible options are:
519 Transaction => <ADDRESS>
525 Reset the status of the server. This may be called after a message has been
526 initiated, but before any data has been sent, to cancel the sending of the
529 =item recipient ( ADDRESS [, ADDRESS [ ...]] [, OPTIONS ] )
531 Notify the server that the current message should be sent to all of the
532 addresses given. Each address is sent as a separate command to the server.
533 Should the sending of any address result in a failure then the
534 process is aborted and a I<false> value is returned. It is up to the
535 user to call C<reset> if they so desire.
537 The C<recipient> method can some additional OPTIONS which is passed
538 in hash like fashion, using key and value pairs. Possible options are:
541 SkipBad => ignore bad addresses
543 If C<SkipBad> is true the C<recipient> will not return an error when a
544 bad address is encountered and it will return an array of addresses
547 =item to ( ADDRESS [, ADDRESS [...]] )
549 A synonym for C<recipient>.
551 =item data ( [ DATA ] )
553 Initiate the sending of the data from the current message.
555 C<DATA> may be a reference to a list or a list. If specified the contents
556 of C<DATA> and a termination string C<".\r\n"> is sent to the server. And the
557 result will be true if the data was accepted.
559 If C<DATA> is not specified then the result will indicate that the server
560 wishes the data to be sent. The data must then be sent using the C<datasend>
561 and C<dataend> methods described in L<Net::Cmd>.
563 =item expand ( ADDRESS )
565 Request the server to expand the given address Returns an array
566 which contains the text read from the server.
568 =item verify ( ADDRESS )
570 Verify that C<ADDRESS> is a legitimate mailing address.
572 =item help ( [ $subject ] )
574 Request help text from the server. Returns the text or undef upon failure
578 Send the QUIT command to the remote SMTP server and close the socket connection.
588 Graham Barr <gbarr@pobox.com>
592 Copyright (c) 1995-1997 Graham Barr. All rights reserved.
593 This program is free software; you can redistribute it and/or modify
594 it under the same terms as Perl itself.