Allow setting an empty envelope-from using '-s'.
[mail/checkmail.git] / checkmail.pl
1 #! /usr/bin/perl -w
2 #
3 # checkmail Version 0.6.1 by Thomas Hochstein
4 #
5 # This script tries to verify the deliverability of (a) mail address(es).
6
7 # Copyright (c) 2002-2011 Thomas Hochstein <thh@inter.net>
8 #
9 # It can be redistributed and/or modified under the same terms under 
10 # which Perl itself is published.
11
12 our $VERSION = "0.6.2";
13
14 ################################# Configuration ################################
15 # Please fill in a working configuration!
16 my %config=(
17             # value used for HELO/EHLO - a valid hostname you own
18             helo => 'testhost.domain.example',
19             # value used for MAIL FROM: - a valid address under your control
20             from => 'mailtest@testhost.domain.example'
21            );
22
23 ################################### Modules ####################################
24 use strict;
25 use File::Basename;
26 use Getopt::Std;
27 use Mail::Address;
28 use Net::DNS;
29 use Net::SMTP;
30
31 ################################# Main program #################################
32
33 $Getopt::Std::STANDARD_HELP_VERSION = 1;
34 my $myself = basename($0);
35
36 # read commandline options
37 my %options;
38 getopts('Vhqlrf:m:s:e:', \%options);
39
40 # -V: display version
41 if ($options{'V'}) {
42   print "$myself v $VERSION\nCopyright (c) 2010-2016 Thomas Hochstein <thh\@inter.net>\n";
43   print "This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.\n";
44   exit(100);
45 };
46
47 # -h: feed myself to perldoc
48 if ($options{'h'}) {
49   exec('perldoc', $0);
50   exit(100);
51 };
52
53 # display usage information if neither -f nor an address are present
54 if (!$options{'f'} and !$ARGV[0]) {
55   print "Usage: $myself [-hqlr] [-m <host>] [-s <from>] [-e <EHLO>] <address>|-f <file>\n";
56   print "Options: -V  display copyright and version\n";
57   print "         -h  show documentation\n";
58   print "         -q  quiet (no output, just exit with 0/1/2/3)\n";
59   print "         -l  extended logging\n";
60   print "         -r  test random address to verify verification\n";
61   print "  -m <host>  no DNS lookup, just test this host\n";
62   print "  -s <from>  override configured value for MAIL FROM\n";
63   print "  -e <EHLO>  override configured value for EHLO\n";
64   print "  <address>  mail address to check\n\n";
65   print "  -f <file>  parse file (one address per line)\n";
66   exit(100);
67 };
68
69 # -s / -e: override configuration
70 $config{'from'} = $options{'s'} if defined($options{'s'});
71 $config{'helo'} = $options{'e'} if $options{'e'};
72
73 # -f: open file and read addresses to @adresses
74 my @addresses;
75 if ($options{'f'}) {
76  if (-e $options{'f'}) {
77   open FILE, "<$options{'f'}" or die("$myself ERROR: Could not open file $options{'f'} for reading: $!");
78  } else {
79   die("$myself ERROR: File $options{'f'} does not exist!\n");
80  };
81  while(<FILE>) {
82   chomp;
83   push(@addresses,$_);
84  };
85  close FILE;
86 # fill @adresses with single address to check
87  } else {
88   push(@addresses,$ARGV[0]);
89 };
90
91 # loop over each address and test it
92 my (%targets,$curstat,$status,$log,$message);
93 foreach (@addresses) {
94   my $address = $_;
95   # regexp taken from http://www.regular-expressions.info/email.html
96   # with escaping of "/" added two times and "*" changed to "+"
97   # in localpart, second alternative
98   if ($address !~ /^(?:[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f]+)")@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i) {
99     printf("  > Address <%s> is syntactically INVALID.\n",$address) if !($options{'q'});
100     $curstat = 2;
101   } else {
102     my $domain = Mail::Address->new('',$address)->host;
103     printf("  * Testing %s ...\n",$address) if !($options{'q'});
104     $log .=  "\n===== BEGIN $address =====\n";
105     # get list of target hosts or take host forced via -m
106     if (!$options{'m'}) {
107             %targets = %{gettargets($domain,\$log)};
108     } else {
109       $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
110       $log .= $message;
111       print "    $message" if !($options{'q'});
112       # just one target host with preference 0
113       $targets{$options{'m'}} = 0;
114     };
115     if (%targets) {
116       $curstat = checkaddress($address,\%targets,\$log);
117     } else {
118       $curstat = 2;
119       $message = 'DNS lookup failure';
120       printf("  > Address is INVALID (%s).\n",$message) if !($options{'q'});
121       $log .= $message . '.';
122     };
123     $log   .=  "====== END $address ======\n";
124   };
125   $status = $curstat if (!defined($status) or $curstat > $status);
126 };
127
128 print $log if ($options{'l'});
129
130 # status 0: valid / batch processing
131 #        1: connection failed or temporary failure
132 #        2: invalid
133 #        3: cannot verify
134 #D print "\n-> EXIT $status\n";
135 exit($status);
136
137 ################################## gettargets ##################################
138 # get mail exchanger(s) or A record(s) for a domain
139 # IN : $domain: domain to query the DNS for
140 # OUT: \%targets: reference to a hash containing a list of target hosts
141 sub gettargets {
142   my ($domain,$logr) = @_;
143   # resolver objekt
144   my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
145
146   my %targets;
147   # get MX record(s) as a list sorted by preference
148   if (my @mxrr = mx($resolver,$domain)) {
149     print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
150     foreach my $rr (@mxrr) {
151          $targets{$rr->exchange} = $rr->preference;
152          $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
153     };
154   # no MX record found; log and try A record(s)
155   } else {
156     print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
157     print("    Falling back to A record ...\n") if !($options{'q'});
158         # get A record(s)
159     if (my $query = $resolver->query($domain,'A','IN')) {
160       print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
161       foreach my $rr ($query->answer) {
162         $targets{$rr->address} = 0;
163         $$logr .= sprintf("- %s\n",$rr->address);
164       };
165     # no A record found either; log and fail
166     } else {
167       print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
168       printf("    %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
169     };
170   };
171   return \%targets;
172 };
173
174 ################################# checkaddress #################################
175 # test address for deliverability
176 # IN : $address: adress to be tested
177 #      \%targets: reference to a hash containing a list of MX hosts
178 #      \$log    : reference to the log (to be printed out via -l)
179 # OUT: ---
180 #      \$log will be changed
181 sub checkaddress {
182   my ($address,$targetsr,$logr) = @_;
183   my %targets = %{$targetsr};
184   my $status;
185   # walk %targets in order of preference
186   foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
187     printf("  / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
188           $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
189           $status = checksmtp($address,$host,$logr);
190           last if ($status != 1);
191   };
192   return $status;
193 };
194
195 ################################### checksmtp ##################################
196 # connect to a remote machine on port 25 and test deliverability of a mail
197 # address by doing the SMTP dialog until RCPT TO stage
198 # IN : $address: address to test
199 #      $target : target host
200 #      \$log    : reference to the log (to be printed out via -l)
201 # OUT: .........: reference to a hash containing a list of target hosts
202 #      \$log will be changed
203 sub checksmtp {
204   my ($address,$target,$logr) = @_;
205   my ($status);
206   # start SMTP connection
207   if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
208     $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
209     $$logr .= "EHLO $config{'helo'}\n";
210     log_smtp_reply($logr,$smtp->code,$smtp->message);
211     $smtp->mail($config{'from'});
212     $$logr .= "MAIL FROM:<$config{'from'}>\n";
213     log_smtp_reply($logr,$smtp->code,$smtp->message);
214     # test address
215     my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
216     # connection failure?
217     if ($success < 0) {
218       $status = connection_failed(@message);
219     # delivery attempt was successful?
220     } elsif ($success) {
221       # -r: try random address (which should be guaranteed to be invalid)
222       if ($options{'r'}) {
223         my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
224         # connection failure?
225         if ($success < 0) {
226           $status = connection_failed(@message);
227           # reset status - the address has been checked and _is_ valid!
228           $status = 3;
229           print "  > Address verification currently impossible. You'll have to try again or send a test mail ...\n" if !($options{'q'});
230         # verification impossible?
231         } elsif ($success) {
232           $status = 3;
233           print "  > Address verification impossible. You'll have to send a test mail ...\n" if !($options{'q'});
234         }
235       }
236       # if -r is not set or status was not set to 3: valid address
237       if (!defined($status)) {
238         $status = 0;
239         print "  > Address is valid.\n" if !($options{'q'});
240       };
241     # delivery attempt failed?
242     } else {
243       $status = 2;
244       print "  > Address is INVALID:\n" if !($options{'q'});
245       print '    ' . join('    ',@message) if !($options{'q'});
246     }
247     # terminate SMTP connection
248     $smtp->quit;
249     $$logr .= "QUIT\n";
250     log_smtp_reply($logr,$smtp->code,$smtp->message);
251   } else {
252     # SMTP connection failed / timeout
253     $status = connection_failed();
254     $$logr .= "---Connection failure---\n";
255   };
256   return $status;
257 }
258
259 ############################### create_rand_addr ###############################
260 # create a random mail address
261 # IN : $domain: the domain part
262 # OUT: $address: the address
263 sub create_rand_addr {
264   my($domain)=@_;
265   my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
266   my $address = '';
267   while (length($address) < 15) { 
268     $address .= substr($allowed, (int(rand(length($allowed)))),1);
269   };
270   return ($address.'@'.$domain);
271 };
272
273 ################################ parse_dns_reply ###############################
274 # parse DNS response codes and return code and description
275 # IN : $response: a DNS response code
276 # OUT: "$response ($desciption)"
277 sub parse_dns_reply {
278   my($response)=@_;
279   my %dnsrespcodes = (NOERROR  => 'empty response',
280                       NXDOMAIN => 'non-existent domain',
281                       SERVFAIL => 'DNS server failure',
282                       REFUSED  => 'DNS query refused',
283                       FORMERR  => 'format error',
284                       NOTIMP   => 'not implemented');
285   if(defined($dnsrespcodes{$response})) {
286     return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
287   } else {
288     return $response;
289   };
290 };
291
292 ############################### print_dns_result ###############################
293 # print and log result of DNS query
294 # IN : $domain: domain the DNS was queried for
295 #      $type  : record type (MX, A, ...)
296 #      $count : number of records found
297 #      $error : DNS response code
298 #      \$log : reference to the log (to be printed out via -l)
299 # OUT: ---
300 #      \$log will be changed
301 sub print_dns_result {
302   my ($domain,$type,$count,$error,$logr) = @_;
303   if (defined($count)) {
304     printf("    %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
305     $$logr .= sprintf("%s DNS record(s):\n",$type);
306   } else {
307     printf("    No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
308     $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
309   };
310   return;
311 };
312
313 ################################## try_rcpt_to #################################
314 # send RCPT TO and return replies
315 # IN : \$smtp    : a reference to an SMTP object
316 #      $recipient: a mail address
317 #      \$log     : reference to the log (to be printed out via -l)
318 # OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
319 #      $code   : SMTP status code
320 #      $message: SMTP status message
321 #      \$log will be changed
322 sub try_rcpt_to {
323   my($smtpr,$recipient,$logr)=@_;
324   $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
325   my $success;
326   $$smtpr->to($recipient);
327   if ($$smtpr->code) {
328     log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
329     $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
330   } else {
331     $success = -1;
332     $$logr .= "---Connection failure---\n";
333   };
334   return ($success,$$smtpr->code,$$smtpr->message);
335 };
336
337 ################################ log_smtp_reply ################################
338 # log result of SMTP command
339 # IN : \$log    : reference to the log (to be printed out via -l)
340 #      $code    : SMTP status code
341 #      @message : SMTP status message
342 # OUT: ---
343 #      \$log will be changed
344 sub log_smtp_reply {
345   my($logr,$code,@message)=@_;
346   $$logr .= sprintf('%s %s',$code,join('- ',@message));
347   return;
348 }
349
350 ############################### analyze_smtp_reply ##############################
351 # analyze SMTP response codes and messages
352 # IN : $code    : SMTP status code
353 #      @message : SMTP status message
354 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
355 sub analyze_smtp_reply {
356   my($code,@message)=@_;
357   my $type = substr($code, 0, 1);
358   if ($type == 2) {
359     return 1;
360   } elsif ($type == 5) {
361     return 0;
362   } elsif ($type == 4) {
363     return -1;
364   };
365   return -1;
366 }
367
368 ############################## connection_failed ###############################
369 # print failure message and return status 1
370 # IN : @message : SMTP status message
371 # OUT: 1
372 sub connection_failed {
373   my(@message)=@_;
374   print "  ! Connection failed or other temporary failure.\n" if !($options{'q'});
375   printf("    %s\n",join('    ',@message)) if @message;
376   return 1;
377 }
378
379 __END__
380
381 ################################ Documentation #################################
382
383 =head1 NAME
384
385 checkmail - check deliverability of a mail address
386
387 =head1 SYNOPSIS
388
389 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>]  [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
390
391 =head1 REQUIREMENTS
392
393 =over 2
394
395 =item -
396
397 Perl 5.8 or later
398
399 =item -
400
401 File::Basename
402
403 =item -
404
405 Getopt::Std
406
407 =item -
408
409 Mail::Address I<(CPAN)>
410
411 =item -
412
413 Net::DNS I<(CPAN)>
414
415 =item -
416
417 Net::SMTP
418
419 =back
420
421 Furthermore you'll need a working DNS installation.
422
423 =head1 DESCRIPTION
424
425 checkmail checks the vailidity / deliverability of a mail address.
426 You may submit just one address as the last argument or a file
427 containing one address on each line using the B<-f> option.
428
429 =head2 Configuration
430
431 For the time being, all configuration is done in the script. You have
432 to set the following elements of the %config hash:
433
434 =over 4
435
436 =item B<$config{'helo'}>
437
438 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
439
440 =item B<$config{'from'}>
441
442 The sender address to be used for I<MAIL FROM> while testing.
443 May be empty ('') to set '<>' as MAIL FROM.
444
445 =back
446
447 You may override that configuration by using the B<-e> and B<-s>
448 command line options.
449
450 =head2 Usage
451
452 After configuring the script you may run your first test with
453
454     checkmail user@example.org
455
456 B<checkmail> will check the address for syntactic validity. If the
457 address is valid, it will try to determine the mail exchanger(s) (MX)
458 responsible for I<example.org> by querying the DNS for the respective
459 MX records and then try to connect via SMTP (on port 25) to each of
460 them in order of precedence (if necessary). It will run through the
461 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
462 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
463 fall back to the I<example.org> host itself, provided there is at
464 least one A record defined in the DNS. If there are neither MX nor A
465 records for I<example.org>, mail is not deliverable and B<checkmail>
466 will fail accordingly. If no host can be reached, B<checkmail> will
467 fail, too. Finally B<checkmail> will fail if mail to the given
468 recipient is not accepted by the respective host.
469
470 If B<checkmail> fails, you'll not be able to deliver mail to that
471 address - at least not using the configured sender address and from
472 the host you're testing from. However, the opposite is not true: a
473 mail you send may still not be delivered even if a test via
474 B<checkmail> succeeds. The receiving entity may reject your mail after
475 the I<DATA> stage, due to content checking or without any special
476 reason, or it may even drop, filter or bounce your mail after finally
477 accepting it. There is no way to be sure a mail will be accepted short
478 of sending a real mail to the address in question.
479
480 You may, however, try to detect hosts that will happily accept any and
481 all recipient in the SMTP dialog and just reject your mail later on,
482 for example to defeat exactly the kind of check you try to do.
483 B<checkmail> will do that by submitting a recipient address that is
484 known to be invalid; if that address is accepted, too, you'll know
485 that you can't reliably check the validity of any address on that
486 host. You can force that check by using the B<-r> option.
487
488 If you don't want to see just the results of your test, you can get a
489 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
490 helpful to test for temporary failure conditions.
491
492 On the other hand you may use the B<-q> option to suppress all output;
493 B<checkmail> will then terminate with one of the following B<exit
494 status>:
495        
496 =over 4
497
498 =item B<0>
499
500 address(es) seem/seems to be valid
501
502 =item B<1>
503
504 temporary error (connection failure or temporary failure)
505
506 =item B<2>
507
508 address is invalid
509
510 =item B<3>
511
512 address cannot reliably be checked (test using B<-r> failed)
513
514 =back
515
516 You can do B<batch processing> using B<-f> and submitting a file with
517 one address on each line. In that case the exit status is set to the
518 highest value generated by testing all addresses, i.e. it is set to
519 B<0> if and only if no adress failed, but to B<2> if even one address
520 failed and to B<3> if even one addresses couldn't reliably be checked.
521
522 And finally you can B<suppress DNS lookups> for MX and A records and
523 just force B<checkmail> to connect to a particular host using the
524 B<-m> option.
525
526 B<Please note:> You shouldn't try to validate addresses while working
527 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
528 to have a closer look on the SMTP dialog yourself.
529
530 B<Please note:> To avoid shell expansion on addresses you submit to
531 B<checkmail>, use B<batch processing>.
532
533 =head1 OPTIONS
534
535 =over 3
536
537 =item B<-V> (version)
538
539 Print out version and copyright information on B<checkmail> and exit.
540
541 =item B<-h> (help)
542
543 Print this man page and exit.
544
545 =item B<-q> (quit)
546
547 Suppress output and just terminate with a specific exit status.
548
549 =item B<-l> (log)
550
551 Log and print out the whole SMTP dialog.
552
553 =item B<-r> (random address)
554
555 Also try a reliably invalid address to catch hosts that try undermine
556 address verification.
557
558 =item B<-m> I<host> (MX to use)
559
560 Force a connection to I<host> to check deliverability to that
561 particular host irrespective of DNS entries. For example:
562
563     checkmail -m test.host.example user@domain.example
564
565 =item B<-s> I<sender> (value for MAIL FROM)
566
567 Override configuration and use I<sender> for MAIL FROM.
568
569 =item B<-e> I<EHLO> (value for EHLO)
570
571 Override configuration and use I<EHLO> for EHLO.
572
573 =item B<-f> I<file> (file)
574
575 Process all addresses from I<file> (one on each line).
576
577 =back
578
579 =head1 INSTALLATION
580
581 Just copy checkmail to some directory and get started.
582
583 You can run your first test with
584
585     checkmail user@example.org
586
587 =head1 ENVIRONMENT
588
589 See documentation of I<Net::DNS::Resolver>.
590
591 =head1 FILES
592
593 =over 4
594
595 =item F<checkmail.pl>
596
597 The script itself.
598
599 =back
600
601 =head1 BUGS
602
603 Please report any bugs or feature request to the author or use the
604 bug tracker at L<http://bugs.th-h.de/>!
605
606 =head1 SEE ALSO
607
608 L<http://th-h.de/download/scripts.php> will have the current
609 version of this program.
610
611 This program is maintained using the Git version control system. You
612 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
613 current development tree or browse it on the web via
614 L<http://code.th-h.de/?p=mail/checkmail.git>.
615
616 =head1 AUTHOR
617
618 Thomas Hochstein <thh@inter.net>
619
620 =head1 COPYRIGHT AND LICENSE
621
622 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
623
624 This program is free software; you may redistribute it and/or modify it
625 under the same terms as Perl itself.
626
627 =cut
This page took 0.027367 seconds and 3 git commands to generate.