checkmail.pl

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