checkmail.pl

   1 #! /usr/bin/perl -W
   2 #
   3 # checkmail Version 0.5 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.5";
  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 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 $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         # verification impossible?
 228         } elsif ($success) {
 229           $status = 3;
 230           print "  > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
 231         }
 232       }
 233       # if -r is not set or status was not set to 3: valid address
 234       if (!defined($status)) {
 235         $status = 0;
 236         print "  > Address is valid.\n" if !($options{'q'});
 237       };
 238     # delivery attempt failed?
 239     } else {
 240       $status = 2;
 241       print "  > Address is INVALID:\n" if !($options{'q'});
 242       print '    ' . join('    ',@message) if !($options{'q'});
 243     }
 244     # terminate SMTP connection
 245     $smtp->quit;
 246     $$logr .= "QUIT\n";
 247     log_smtp_reply($logr,$smtp->code,$smtp->message);
 248   } else {
 249     # SMTP connection failed / timeout
 250     $status = connection_failed();
 251     $$logr .= "---Connection failure---\n";
 252   };
 253   return $status;
 254 }
 255
 256 ############################### create_rand_addr ###############################
 257 # create a random mail address
 258 # IN : $domain: the domain part
 259 # OUT: $address: the address
 260 sub create_rand_addr {
 261   my($domain)=@_;
 262   my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
 263   my $address = '';
 264   while (length($address) < 15) {
 265     $address .= substr($allowed, (int(rand(length($allowed)))),1);
 266   };
 267   return ($address.'@'.$domain);
 268 };
 269
 270 ################################ parse_dns_reply ###############################
 271 # parse DNS response codes and return code and description
 272 # IN : $response: a DNS response code
 273 # OUT: "$response ($desciption)"
 274 sub parse_dns_reply {
 275   my($response)=@_;
 276   my %dnsrespcodes = (NOERROR  => 'empty response',
 277                       NXDOMAIN => 'non-existent domain',
 278                       SERVFAIL => 'DNS server failure',
 279                       REFUSED  => 'DNS query refused',
 280                       FORMERR  => 'format error',
 281                       NOTIMP   => 'not implemented');
 282   if(defined($dnsrespcodes{$response})) {
 283     return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
 284   } else {
 285     return $response;
 286   };
 287 };
 288
 289 ############################### print_dns_result ###############################
 290 # print and log result of DNS query
 291 # IN : $domain: domain the DNS was queried for
 292 #      $type  : record type (MX, A, ...)
 293 #      $count : number of records found
 294 #      $error : DNS response code
 295 #      \$log : reference to the log (to be printed out via -l)
 296 # OUT: ---
 297 #      \$log will be changed
 298 sub print_dns_result {
 299   my ($domain,$type,$count,$error,$logr) = @_;
 300   if (defined($count)) {
 301     printf("    %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
 302     $$logr .= sprintf("%s DNS record(s):\n",$type);
 303   } else {
 304     printf("    No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
 305     $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
 306   };
 307   return;
 308 };
 309
 310 ################################## try_rcpt_to #################################
 311 # send RCPT TO and return replies
 312 # IN : \$smtp    : a reference to an SMTP object
 313 #      $recipient: a mail address
 314 #      \$log     : reference to the log (to be printed out via -l)
 315 # OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
 316 #      $code   : SMTP status code
 317 #      $message: SMTP status message
 318 #      \$log will be changed
 319 sub try_rcpt_to {
 320   my($smtpr,$recipient,$logr)=@_;
 321   $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
 322   my $success;
 323   $$smtpr->to($recipient);
 324   if ($$smtpr->code) {
 325     log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
 326     $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
 327   } else {
 328     $success = -1;
 329     $$logr .= "---Connection failure---\n";
 330   };
 331   return ($success,$$smtpr->code,$$smtpr->message);
 332 };
 333
 334 ################################ log_smtp_reply ################################
 335 # log result of SMTP command
 336 # IN : \$log    : reference to the log (to be printed out via -l)
 337 #      $code    : SMTP status code
 338 #      @message : SMTP status message
 339 # OUT: ---
 340 #      \$log will be changed
 341 sub log_smtp_reply {
 342   my($logr,$code,@message)=@_;
 343   $$logr .= sprintf('%s %s',$code,join('- ',@message));
 344   return;
 345 }
 346
 347 ############################### analyze_smtp_reply ##############################
 348 # analyze SMTP response codes and messages
 349 # IN : $code    : SMTP status code
 350 #      @message : SMTP status message
 351 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
 352 sub analyze_smtp_reply {
 353   my($code,@message)=@_;
 354   my $type = substr($code, 0, 1);
 355   if ($type == 2) {
 356     return 1;
 357   } elsif ($type == 5) {
 358     return 0;
 359   } elsif ($type == 4) {
 360     return -1;
 361   };
 362   return -1;
 363 }
 364
 365 ############################## connection_failed ###############################
 366 # print failure message and return status 1
 367 # IN : @message : SMTP status message
 368 # OUT: 1
 369 sub connection_failed {
 370   my(@message)=@_;
 371   print "  ! Connection failed or other temporary failure.\n" if !($options{'q'});
 372   printf("    %s\n",join('    ',@message)) if @message;
 373   return 1;
 374 }
 375
 376 __END__
 377
 378 ################################ Documentation #################################
 379
 380 =head1 NAME
 381
 382 checkmail - check deliverability of a mail address
 383
 384 =head1 SYNOPSIS
 385
 386 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>]  [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
 387
 388 =head1 REQUIREMENTS
 389
 390 =over 2
 391
 392 =item -
 393
 394 Perl 5.8 or later
 395
 396 =item -
 397
 398 File::Basename
 399
 400 =item -
 401
 402 Getopt::Std
 403
 404 =item -
 405
 406 Mail::Address I<(CPAN)>
 407
 408 =item -
 409
 410 Net::DNS I<(CPAN)>
 411
 412 =item -
 413
 414 Net::SMTP
 415
 416 =back
 417
 418 Furthermore you'll need a working DNS installation.
 419
 420 =head1 DESCRIPTION
 421
 422 checkmail checks the vailidity / deliverability of a mail address.
 423 You may submit just one address as the last argument or a file
 424 containing one address on each line using the B<-f> option.
 425
 426 =head2 Configuration
 427
 428 For the time being, all configuration is done in the script. You have
 429 to set the following elements of the %config hash:
 430
 431 =over 4
 432
 433 =item B<$config{'helo'}>
 434
 435 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
 436
 437 =item B<$config{'from'}>
 438
 439 The sender address to be used for I<MAIL FROM> while testing.
 440
 441 =back
 442
 443 You may override that configuration by using the B<-e> and B<-s>
 444 command line options.
 445
 446 =head2 Usage
 447
 448 After configuring the script you may run your first test with
 449
 450     checkmail user@example.org
 451
 452 B<checkmail> will check the address for syntactic validity. If the
 453 address is valid, it will try to determine the mail exchanger(s) (MX)
 454 responsible for I<example.org> by querying the DNS for the respective
 455 MX records and then try to connect via SMTP (on port 25) to each of
 456 them in order of precedence (if necessary). It will run through the
 457 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
 458 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
 459 fall back to the I<example.org> host itself, provided there is at
 460 least one A record defined in the DNS. If there are neither MX nor A
 461 records for I<example.org>, mail is not deliverable and B<checkmail>
 462 will fail accordingly. If no host can be reached, B<checkmail> will
 463 fail, too. Finally B<checkmail> will fail if mail to the given
 464 recipient is not accepted by the respective host.
 465
 466 If B<checkmail> fails, you'll not be able to deliver mail to that
 467 address - at least not using the configured sender address and from
 468 the host you're testing from. However, the opposite is not true: a
 469 mail you send may still not be delivered even if a test via
 470 B<checkmail> succeeds. The receiving entity may reject your mail after
 471 the I<DATA> stage, due to content checking or without any special
 472 reason, or it may even drop, filter or bounce your mail after finally
 473 accepting it. There is no way to be sure a mail will be accepted short
 474 of sending a real mail to the address in question.
 475
 476 You may, however, try to detect hosts that will happily accept any and
 477 all recipient in the SMTP dialog and just reject your mail later on,
 478 for example to defeat exactly the kind of check you try to do.
 479 B<checkmail> will do that by submitting a recipient address that is
 480 known to be invalid; if that address is accepted, too, you'll know
 481 that you can't reliably check the validity of any address on that
 482 host. You can force that check by using the B<-r> option.
 483
 484 If you don't want to see just the results of your test, you can get a
 485 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
 486 helpful to test for temporary failure conditions.
 487
 488 On the other hand you may use the B<-q> option to suppress all output;
 489 B<checkmail> will then terminate with one of the following B<exit
 490 status>:
 491
 492 =over 4
 493
 494 =item B<0>
 495
 496 address(es) seem/seems to be valid
 497
 498 =item B<1>
 499
 500 temporary error (connection failure or temporary failure)
 501
 502 =item B<2>
 503
 504 address is invalid
 505
 506 =item B<3>
 507
 508 address cannot reliably be checked (test using B<-r> failed)
 509
 510 =back
 511
 512 You can do B<batch processing> using B<-f> and submitting a file with
 513 one address on each line. In that case the exit status is set to the
 514 highest value generated by testing all addresses, i.e. it is set to
 515 B<0> if and only if no adress failed, but to B<2> if even one address
 516 failed and to B<3> if even one addresses couldn't reliably be checked.
 517
 518 And finally you can B<suppress DNS lookups> for MX and A records and
 519 just force B<checkmail> to connect to a particular host using the
 520 B<-m> option.
 521
 522 B<Please note:> You shouldn't try to validate addresses while working
 523 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
 524 to have a closer look on the SMTP dialog yourself.
 525
 526 B<Please note:> To avoid shell expansion on addresses you submit to
 527 B<checkmail>, use B<batch processing>.
 528
 529 =head1 OPTIONS
 530
 531 =over 3
 532
 533 =item B<-V> (version)
 534
 535 Print out version and copyright information on B<checkmail> and exit.
 536
 537 =item B<-h> (help)
 538
 539 Print this man page and exit.
 540
 541 =item B<-q> (quit)
 542
 543 Suppress output and just terminate with a specific exit status.
 544
 545 =item B<-l> (log)
 546
 547 Log and print out the whole SMTP dialog.
 548
 549 =item B<-r> (random address)
 550
 551 Also try a reliably invalid address to catch hosts that try undermine
 552 address verification.
 553
 554 =item B<-m> I<host> (MX to use)
 555
 556 Force a connection to I<host> to check deliverability to that
 557 particular host irrespective of DNS entries. For example:
 558
 559     checkmail -m test.host.example user@domain.example
 560
 561 =item B<-s> I<sender> (value for MAIL FROM)
 562
 563 Override configuration and use I<sender> for MAIL FROM.
 564
 565 =item B<-e> I<EHLO> (value for EHLO)
 566
 567 Override configuration and use I<EHLO> for EHLO.
 568
 569 =item B<-f> I<file> (file)
 570
 571 Process all addresses from I<file> (one on each line).
 572
 573 =back
 574
 575 =head1 INSTALLATION
 576
 577 Just copy checkmail to some directory and get started.
 578
 579 You can run your first test with
 580
 581     checkmail user@example.org
 582
 583 =head1 ENVIRONMENT
 584
 585 See documentation of I<Net::DNS::Resolver>.
 586
 587 =head1 FILES
 588
 589 =over 4
 590
 591 =item F<checkmail.pl>
 592
 593 The script itself.
 594
 595 =back
 596
 597 =head1 BUGS
 598
 599 Please report any bugs or feature request to the author or use the
 600 bug tracker at L<http://bugs.th-h.de/>!
 601
 602 =head1 SEE ALSO
 603
 604 L<http://th-h.de/download/scripts.php> will have the current
 605 version of this program.
 606
 607 This program is maintained using the Git version control system. You
 608 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
 609 current development tree or browse it on the web via
 610 L<http://code.th-h.de/?p=mail/checkmail.git>.
 611
 612 =head1 AUTHOR
 613
 614 Thomas Hochstein <thh@inter.net>
 615
 616 =head1 COPYRIGHT AND LICENSE
 617
 618 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
 619
 620 This program is free software; you may redistribute it and/or modify it
 621 under the same terms as Perl itself.
 622
 623 =cut