checkmail.pl

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