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-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";
  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           # 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
 444 =back
 445
 446 You may override that configuration by using the B<-e> and B<-s>
 447 command line options.
 448
 449 =head2 Usage
 450
 451 After configuring the script you may run your first test with
 452
 453     checkmail user@example.org
 454
 455 B<checkmail> will check the address for syntactic validity. If the
 456 address is valid, it will try to determine the mail exchanger(s) (MX)
 457 responsible for I<example.org> by querying the DNS for the respective
 458 MX records and then try to connect via SMTP (on port 25) to each of
 459 them in order of precedence (if necessary). It will run through the
 460 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
 461 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
 462 fall back to the I<example.org> host itself, provided there is at
 463 least one A record defined in the DNS. If there are neither MX nor A
 464 records for I<example.org>, mail is not deliverable and B<checkmail>
 465 will fail accordingly. If no host can be reached, B<checkmail> will
 466 fail, too. Finally B<checkmail> will fail if mail to the given
 467 recipient is not accepted by the respective host.
 468
 469 If B<checkmail> fails, you'll not be able to deliver mail to that
 470 address - at least not using the configured sender address and from
 471 the host you're testing from. However, the opposite is not true: a
 472 mail you send may still not be delivered even if a test via
 473 B<checkmail> succeeds. The receiving entity may reject your mail after
 474 the I<DATA> stage, due to content checking or without any special
 475 reason, or it may even drop, filter or bounce your mail after finally
 476 accepting it. There is no way to be sure a mail will be accepted short
 477 of sending a real mail to the address in question.
 478
 479 You may, however, try to detect hosts that will happily accept any and
 480 all recipient in the SMTP dialog and just reject your mail later on,
 481 for example to defeat exactly the kind of check you try to do.
 482 B<checkmail> will do that by submitting a recipient address that is
 483 known to be invalid; if that address is accepted, too, you'll know
 484 that you can't reliably check the validity of any address on that
 485 host. You can force that check by using the B<-r> option.
 486
 487 If you don't want to see just the results of your test, you can get a
 488 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
 489 helpful to test for temporary failure conditions.
 490
 491 On the other hand you may use the B<-q> option to suppress all output;
 492 B<checkmail> will then terminate with one of the following B<exit
 493 status>:
 494
 495 =over 4
 496
 497 =item B<0>
 498
 499 address(es) seem/seems to be valid
 500
 501 =item B<1>
 502
 503 temporary error (connection failure or temporary failure)
 504
 505 =item B<2>
 506
 507 address is invalid
 508
 509 =item B<3>
 510
 511 address cannot reliably be checked (test using B<-r> failed)
 512
 513 =back
 514
 515 You can do B<batch processing> using B<-f> and submitting a file with
 516 one address on each line. In that case the exit status is set to the
 517 highest value generated by testing all addresses, i.e. it is set to
 518 B<0> if and only if no adress failed, but to B<2> if even one address
 519 failed and to B<3> if even one addresses couldn't reliably be checked.
 520
 521 And finally you can B<suppress DNS lookups> for MX and A records and
 522 just force B<checkmail> to connect to a particular host using the
 523 B<-m> option.
 524
 525 B<Please note:> You shouldn't try to validate addresses while working
 526 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
 527 to have a closer look on the SMTP dialog yourself.
 528
 529 B<Please note:> To avoid shell expansion on addresses you submit to
 530 B<checkmail>, use B<batch processing>.
 531
 532 =head1 OPTIONS
 533
 534 =over 3
 535
 536 =item B<-V> (version)
 537
 538 Print out version and copyright information on B<checkmail> and exit.
 539
 540 =item B<-h> (help)
 541
 542 Print this man page and exit.
 543
 544 =item B<-q> (quit)
 545
 546 Suppress output and just terminate with a specific exit status.
 547
 548 =item B<-l> (log)
 549
 550 Log and print out the whole SMTP dialog.
 551
 552 =item B<-r> (random address)
 553
 554 Also try a reliably invalid address to catch hosts that try undermine
 555 address verification.
 556
 557 =item B<-m> I<host> (MX to use)
 558
 559 Force a connection to I<host> to check deliverability to that
 560 particular host irrespective of DNS entries. For example:
 561
 562     checkmail -m test.host.example user@domain.example
 563
 564 =item B<-s> I<sender> (value for MAIL FROM)
 565
 566 Override configuration and use I<sender> for MAIL FROM.
 567
 568 =item B<-e> I<EHLO> (value for EHLO)
 569
 570 Override configuration and use I<EHLO> for EHLO.
 571
 572 =item B<-f> I<file> (file)
 573
 574 Process all addresses from I<file> (one on each line).
 575
 576 =back
 577
 578 =head1 INSTALLATION
 579
 580 Just copy checkmail to some directory and get started.
 581
 582 You can run your first test with
 583
 584     checkmail user@example.org
 585
 586 =head1 ENVIRONMENT
 587
 588 See documentation of I<Net::DNS::Resolver>.
 589
 590 =head1 FILES
 591
 592 =over 4
 593
 594 =item F<checkmail.pl>
 595
 596 The script itself.
 597
 598 =back
 599
 600 =head1 BUGS
 601
 602 Please report any bugs or feature request to the author or use the
 603 bug tracker at L<http://bugs.th-h.de/>!
 604
 605 =head1 SEE ALSO
 606
 607 L<http://th-h.de/download/scripts.php> will have the current
 608 version of this program.
 609
 610 This program is maintained using the Git version control system. You
 611 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
 612 current development tree or browse it on the web via
 613 L<http://code.th-h.de/?p=mail/checkmail.git>.
 614
 615 =head1 AUTHOR
 616
 617 Thomas Hochstein <thh@inter.net>
 618
 619 =head1 COPYRIGHT AND LICENSE
 620
 621 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
 622
 623 This program is free software; you may redistribute it and/or modify it
 624 under the same terms as Perl itself.
 625
 626 =cut