3 # Copyright (c) 1995 Graham Barr <Graham.Barr@tiuk.ti.com>. All rights
4 # reserved. This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
11 Net::SMTP - Simple Mail transfer Protocol Client
18 $smtp = Net::SMTP->new('mailhost');
19 $smtp = Net::SMTP->new('mailhost', Timeout => 60);
23 This module implements a client interface to the SMTP protocol, enabling
24 a perl5 application to talk to SMTP servers. This documentation assumes
25 that you are familiar with the SMTP protocol described in RFC821.
27 A new Net::SMTP object must be created with the I<new> method. Once
28 this has been done, all SMTP commands are accessed through this object.
32 This example prints the mail domain name of the SMTP server known as mailhost:
34 #!/usr/local/bin/perl -w
38 $smtp = Net::SMTP->new('mailhost');
40 print $smtp->domain,"\n";
44 This example sends a small message to the postmaster at the SMTP server
47 #!/usr/local/bin/perl -w
51 $smtp = Net::SMTP->new('mailhost');
53 $smtp->mail($ENV{USER});
55 $smtp->to('postmaster');
59 $smtp->datasend("To: postmaster\n");
60 $smtp->datasend("\n");
61 $smtp->datasend("A simple test message\n");
71 =item new ( HOST, [ OPTIONS ] )
73 This is the constructor for a new Net::SMTP object. C<HOST> is the
74 name of the remote host to which a SMTP connection is required.
76 C<OPTIONS> are passed in a hash like fasion, using key and value pairs.
79 B<Hello> - SMTP requires that you identify yourself. This option
80 specifies a string to pass as your mail domain. If not
81 given a guess will be taken.
83 B<Timeout> - Maximum time, in seconds, to wait for a response from the
84 SMTP server (default: 120)
86 B<Debug> - Enable debugging information
92 $smtp = Net::SMTP->new('mailhost',
93 Hello => 'my.mail.domain'
98 Unless otherwise stated all methods return either a I<true> or I<false>
99 value, with I<true> meaning that the operation was a success. When a method
100 states that it returns a value, falure will be returned as I<undef> or an
107 Returns the domain that the remote SMTP server identified itself as during
110 =item hello ( DOMAIN )
112 Tell the remote server the mail domain which you are in using the HELO
115 =item mail ( ADDRESS )
117 =item send ( ADDRESS )
119 =item send_or_mail ( ADDRESS )
121 =item send_and_mail ( ADDRESS )
123 Send the appropriate command to the server MAIL, SEND, SOML or SAML. C<ADDRESS>
124 is the address of the sender. This initiates the sending of a message. The
125 method C<recipient> should be called for each address that the message is to
130 Reset the status of the server. This may be called after a message has been
131 initiated, but before any data has been sent, to cancel the sending of the
134 =item recipient ( ADDRESS [, ADDRESS [ ...]] )
136 Notify the server that the current message should be sent to all of the
137 addresses given. Each address is sent as a separate command to the server.
138 Should the sending of any address result in a failure then the
139 process is aborted and a I<false> value is returned. It is up to the
140 user to call C<reset> if they so desire.
144 A synonym for recipient
146 =item data ( [ DATA ] )
148 Initiate the sending of the data fro the current message.
150 C<DATA> may be a reference to a list or a list. If specified the contents
151 of C<DATA> and a termination string C<".\r\n"> is sent to the server. And the
152 result will be true if the data was accepted.
154 If C<DATA> is not specified then the result will indicate that the server
155 wishes the data to be sent. The data must then be sent using the C<datasend>
156 and C<dataend> methods defined in C<Net::Cmd>.
158 =item expand ( ADDRESS )
160 Request the server to expand the given address Returns a reference to an array
161 which contains the text read from the server.
163 =item verify ( ADDRESS )
165 Verify that C<ADDRESS> is a legitimate mailing address.
167 =item help ( [ $subject ] )
169 Request help text from the server. Returns the text or undef upon failure
173 Send the QUIT command to the remote SMTP server and close the socket connection.
183 Graham Barr <Graham.Barr@tiuk.ti.com>
188 $Date: 1996/08/20 20:23:56 $
190 The VERSION is derived from the revision by changing each number after the
191 first dot into a 2 digit number so
193 Revision 1.8 => VERSION 1.08
194 Revision 1.2.3 => VERSION 1.0203
198 Copyright (c) 1995 Graham Barr. All rights reserved. This program is free
199 software; you can redistribute it and/or modify it under the same terms
207 use vars qw($VERSION @ISA);
213 $VERSION = do{my @r=(q$Revision: 2.1 $=~/(\d+)/g);sprintf "%d."."%02d"x$#r,@r};
215 @ISA = qw(Net::Cmd IO::Socket::INET);
220 my $type = ref($self) || $self;
223 my $obj = $type->SUPER::new(PeerAddr => $host,
224 PeerPort => $arg{Port} || 'smtp(25)',
226 Timeout => defined $arg{Timeout}
233 $obj->debug(exists $arg{Debug} ? $arg{Debug} : undef);
235 unless ($obj->response() == CMD_OK)
237 $obj->SUPER::close();
241 ${*$obj}{'net_smtp_host'} = $host;
243 (${*$obj}{'net_smtp_domain'}) = $obj->message =~ /\A\s*(\S+)/;
245 $obj->hello($arg{Hello} || "");
251 ## User interface methods
258 return ${*$me}{'net_smtp_domain'} || undef;
264 my $domain = shift ||
267 Net::Domain::hostdomain();
270 my $ok = $me->_EHLO($domain);
277 my $h = ${*$me}{'net_smtp_esmtp'} = {};
279 foreach $ext (qw(8BITMIME CHECKPOINT DSN SIZE))
282 if $msg =~ /\b${ext}\b/;
288 if $me->_HELO($domain);
291 $ok && $msg =~ /\A(\S+)/
298 my $addr = shift || "";
301 if $addr =~ /(<[^>]+>)/so;
304 $addr =~ s/(\A\s+|\s+\Z)//sog;
306 return "<" . $addr . ">";
313 my $addr = _addr(shift);
321 if(exists ${*$me}{'net_smtp_esmtp'})
323 my $esmtp = ${*$me}{'net_smtp_esmtp'};
325 if(defined($v = delete $opt{Size}))
327 if(exists $esmtp->{SIZE})
329 $opts .= sprintf " SIZE=%d", $v + 0
333 carp 'Net::SMTP::mail: SIZE option not supported by host';
337 if(defined($v = delete $opt{Return}))
339 if(exists $esmtp->{DSN})
341 $opts .= " RET=" . uc $v
345 carp 'Net::SMTP::mail: DSN option not supported by host';
349 if(defined($v = delete $opt{Bits}))
351 if(exists $esmtp->{'8BITMIME'})
353 $opts .= $v == 8 ? " BODY=8BITMIME" : " BODY=7BIT"
357 carp 'Net::SMTP::mail: 8BITMIME option not supported by host';
361 if(defined($v = delete $opt{Transaction}))
363 if(exists $esmtp->{CHECKPOINT})
365 $opts .= " TRANSID=" . _addr($v);
369 carp 'Net::SMTP::mail: CHECKPOINT option not supported by host';
373 if(defined($v = delete $opt{Envelope}))
375 if(exists $esmtp->{DSN})
377 $v =~ s/([^\041-\176]|=|\+)/sprintf "+%02x", ord($1)/sge;
382 carp 'Net::SMTP::mail: DSN option not supported by host';
386 carp 'Net::SMTP::recipient: unknown option(s) '
387 . join(" ", keys %opt)
393 carp 'Net::SMTP::mail: ESMTP not supported by host - options discarded :-(';
397 $me->_MAIL("FROM:".$addr.$opts);
400 sub send { shift->_SEND("FROM:" . _addr($_[0])) }
401 sub send_or_mail { shift->_SOML("FROM:" . _addr($_[0])) }
402 sub send_and_mail { shift->_SAML("FROM:" . _addr($_[0])) }
409 if(exists ${*$me}{'net_smtp_lastch'});
421 if(@_ && ref($_[-1]))
423 my %opt = %{pop(@_)};
426 if(exists ${*$smtp}{'net_smtp_esmtp'})
428 my $esmtp = ${*$smtp}{'net_smtp_esmtp'};
430 if(defined($v = delete $opt{Notify}))
432 if(exists $esmtp->{DSN})
434 $opts .= " NOTIFY=" . join(",",map { uc $_ } @$v)
438 carp 'Net::SMTP::recipient: DSN option not supported by host';
442 carp 'Net::SMTP::recipient: unknown option(s) '
443 . join(" ", keys %opt)
449 carp 'Net::SMTP::recipient: ESMTP not supported by host - options discarded :-(';
453 while($ok && scalar(@_))
455 $ok = $smtp->_RCPT("TO:" . _addr(shift) . $opts);
467 my $ok = $me->_DATA() && $me->datasend(@_);
469 $ok && @_ ? $me->dataend
477 $me->_EXPN(@_) ? ($me->message)
482 sub verify { shift->_VRFY(@_) }
488 $me->_HELP(@_) ? scalar $me->message
497 unless (ref($me) && defined fileno($me));
499 $me->_QUIT && $me->SUPER::close;
502 sub DESTROY { shift->close }
503 sub quit { shift->close }
509 sub _EHLO { shift->command("EHLO", @_)->response() == CMD_OK }
510 sub _HELO { shift->command("HELO", @_)->response() == CMD_OK }
511 sub _MAIL { shift->command("MAIL", @_)->response() == CMD_OK }
512 sub _RCPT { shift->command("RCPT", @_)->response() == CMD_OK }
513 sub _SEND { shift->command("SEND", @_)->response() == CMD_OK }
514 sub _SAML { shift->command("SAML", @_)->response() == CMD_OK }
515 sub _SOML { shift->command("SOML", @_)->response() == CMD_OK }
516 sub _VRFY { shift->command("VRFY", @_)->response() == CMD_OK }
517 sub _EXPN { shift->command("EXPN", @_)->response() == CMD_OK }
518 sub _HELP { shift->command("HELP", @_)->response() == CMD_OK }
519 sub _RSET { shift->command("RSET")->response() == CMD_OK }
520 sub _NOOP { shift->command("NOOP")->response() == CMD_OK }
521 sub _QUIT { shift->command("QUIT")->response() == CMD_OK }
522 sub _DATA { shift->command("DATA")->response() == CMD_MORE }
523 sub _TURN { shift->unsupported(@_); }