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