[mail/checkmail.git] / checkmail.pl

#! /usr/bin/perl -W
#
# checkmail Version 0.3 by Thomas Hochstein
#
# This script tries to verify the deliverability of (a) mail address(es).
# 
# Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
#
# It can be redistributed and/or modified under the same terms under 
# which Perl itself is published.

our $VERSION = "0.3";

################################# Configuration ################################
# Please fill in a working configuration!
my %config=(
            # value used for HELO/EHLO - a valid hostname you own
            helo => 'testhost.domain.example',
            # value used for MAIL FROM: - a valid address under your control
            from => 'mailtest@testhost.domain.example'
           );

################################### Modules ####################################
use strict;
use File::Basename;
use Getopt::Std;
use Mail::Address;
use Net::DNS;
use Net::SMTP;

################################# Main program #################################

$Getopt::Std::STANDARD_HELP_VERSION = 1;
my $myself = basename($0);

# read commandline options
my %options;
getopts('Vhqlrf:m:', \%options);

# -V: display version
if ($options{'V'}) {
  print "$myself v $VERSION\nCopyright (c) 2010 Thomas Hochstein <thh\@inter.net>\n";
  print "This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.\n";
  exit(100);
};

# -h: feed myself to perldoc
if ($options{'h'}) {
  exec('perldoc', $0);
  exit(100);
};

# display usage information if neither -f nor an address are present
if (!$options{'f'} and !$ARGV[0]) {
  print "Usage: $myself [-hqlr] [-m <host>] <address>|-f <file>\n";
  print "Options: -V  display copyright and version\n";
  print "         -h  show documentation\n";
  print "         -q  quiet (no output, just exit with 0/1/2/3)\n";
  print "         -l  extended logging\n";
  print "         -r  test random address to verify verification\n";
  print "  -m <host>  no DNS lookup, just test this host\n";
  print "  <address>  mail address to check\n\n";
  print "  -f <file>  parse file (one address per line)\n";
  exit(100);
};

# -f: open file and read addresses to @adresses
my @addresses;
if ($options{'f'}) {
 if (-e $options{'f'}) {
  open FILE, "<$options{'f'}" or die("$myself ERROR: Could not open file $options{'f'} for reading: $!");
 } else {
  die("$myself ERROR: File $options{'f'} does not exist!\n");
 };
 while(<FILE>) {
  chomp;
  push(@addresses,$_);
 };
 close FILE;
# fill @adresses with single address to check
 } else {
  push(@addresses,$ARGV[0]);
};

# loop over each address and test it
my (%targets,$curstat,$status,$log,$message);
foreach (@addresses) {
  my $address = $_;
  my $domain = Mail::Address->new('',$address)->host;
  printf("  * Testing %s ...\n",$address) if !($options{'q'});
  $log .=  "\n===== BEGIN $address =====\n";
  # get list of target hosts or take host forced via -m
  if (!$options{'m'}) {
	  %targets = %{gettargets($domain,\$log)};
  } else {
    $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
    $log .= $message;
    print "    $message" if !($options{'q'});
    # just one target host with preference 0
    $targets{$options{'m'}} = 0;
  };
  if (%targets) {
    $curstat = checkaddress($address,\%targets,\$log);
  } else {
    $curstat = 2;
    $message = 'DNS lookup failure';
    printf("  > Address is INVALID (%s).\n",$message) if !($options{'q'});
    $log .= $message . '.';
  };
  $log   .=  "====== END $address ======\n";
  $status = $curstat if (!defined($status) or $curstat > $status);
};

print $log if ($options{'l'});

# status 0: valid / batch processing
#        1: connection failed or temporary failure
#        2: invalid
#        3: cannot verify
#D print "\n-> EXIT $status\n";
exit($status);

################################## gettargets ##################################
# get mail exchanger(s) or A record(s) for a domain
# IN : $domain: domain to query the DNS for
# OUT: \%targets: reference to a hash containing a list of target hosts
sub gettargets {
  my ($domain,$logr) = @_;
  # resolver objekt
  my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);

  my %targets;
  # get MX record(s) as a list sorted by preference
  if (my @mxrr = mx($resolver,$domain)) {
    print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
    foreach my $rr (@mxrr) {
	 $targets{$rr->exchange} = $rr->preference;
	 $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
    };
  # no MX record found; log and try A record(s)
  } else {
    print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
    print("    Falling back to A record ...\n") if !($options{'q'});
	# get A record(s)
    if (my $query = $resolver->query($domain,'A','IN')) {
      print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
      foreach my $rr ($query->answer) {
        $targets{$rr->address} = 0;
        $$logr .= sprintf("- %s\n",$rr->address);
      };
    # no A record found either; log and fail
    } else {
      print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
      printf("    %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
    };
  };
  return \%targets;
};

################################# checkaddress #################################
# test address for deliverability
# IN : $address: adress to be tested
#      \%targets: reference to a hash containing a list of MX hosts
#      \$log    : reference to the log (to be printed out via -l)
# OUT: ---
#      \$log will be changed
sub checkaddress {
  my ($address,$targetsr,$logr) = @_;
  my %targets = %{$targetsr};
  my $status;
  # walk %targets in order of preference
  foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
    printf("  / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
	  $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
	  $status = checksmtp($address,$host,$logr);
	  last if ($status != 1);
  };
  return $status;
};

################################### checksmtp ##################################
# connect to a remote machine on port 25 and test deliverability of a mail
# address by doing the SMTP dialog until RCPT TO stage
# IN : $address: address to test
#      $target : target host
#      \$log    : reference to the log (to be printed out via -l)
# OUT: .........: reference to a hash containing a list of target hosts
#      \$log will be changed
sub checksmtp {
  my ($address,$target,$logr) = @_;
  my ($status);
  # start SMTP connection
  if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
    $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
    $$logr .= "EHLO $config{'helo'}\n";
    log_smtp_reply($logr,$smtp->code,$smtp->message);
    $smtp->mail($config{'from'});
    $$logr .= "MAIL FROM:<$config{'from'}>\n";
    log_smtp_reply($logr,$smtp->code,$smtp->message);
    # test address
    my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
    # connection failure?
    if ($success < 0) {
      $status = connection_failed(@message);
    # delivery attempt was successful?
    } elsif ($success) {
      # -r: try random address (which should be guaranteed to be invalid)
      if ($options{'r'}) {
        my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
        # connection failure?
        if ($success < 0) {
          $status = connection_failed(@message);
        # verification impossible?
        } elsif ($success) {
          $status = 3;
          print "  > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
        }
      }
      # if -r is not set or status was not set to 3: valid address
      if (!defined($status)) {
        $status = 0;
        print "  > Address is valid.\n" if !($options{'q'});
      };
    # delivery attempt failed?
    } else {
      $status = 2;
      print "  > Address is INVALID:\n" if !($options{'q'});
      print '    ' . join('    ',@message) if !($options{'q'});
    }
    # terminate SMTP connection
    $smtp->quit;
    $$logr .= "QUIT\n";
    log_smtp_reply($logr,$smtp->code,$smtp->message);
  } else {
    # SMTP connection failed / timeout
    $status = connection_failed();
    $$logr .= "---Connection failure---\n";
  };
  return $status;
}

############################### create_rand_addr ###############################
# create a random mail address
# IN : $domain: the domain part
# OUT: $address: the address
sub create_rand_addr {
  my($domain)=@_;
  my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
  my $address = '';
  while (length($address) < 15) { 
    $address .= substr($allowed, (int(rand(length($allowed)))),1);
  };
  return ($address.'@'.$domain);
};

################################ parse_dns_reply ###############################
# parse DNS response codes and return code and description
# IN : $response: a DNS response code
# OUT: "$response ($desciption)"
sub parse_dns_reply {
  my($response)=@_;
  my %dnsrespcodes = (NOERROR  => 'empty response',
                      NXDOMAIN => 'non-existent domain',
                      SERVFAIL => 'DNS server failure',
                      REFUSED  => 'DNS query refused',
                      FORMERR  => 'format error',
                      NOTIMP   => 'not implemented');
  if(defined($dnsrespcodes{$response})) {
    return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
  } else {
    return $response;
  };
};

############################### print_dns_result ###############################
# print and log result of DNS query
# IN : $domain: domain the DNS was queried for
#      $type  : record type (MX, A, ...)
#      $count : number of records found
#      $error : DNS response code
#      \$log : reference to the log (to be printed out via -l)
# OUT: ---
#      \$log will be changed
sub print_dns_result {
  my ($domain,$type,$count,$error,$logr) = @_;
  if (defined($count)) {
    printf("    %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
    $$logr .= sprintf("%s DNS record(s):\n",$type);
  } else {
    printf("    No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
    $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
  };
  return;
};

################################## try_rcpt_to #################################
# send RCPT TO and return replies
# IN : \$smtp    : a reference to an SMTP object
#      $recipient: a mail address
#      \$log     : reference to the log (to be printed out via -l)
# OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
#      $code   : SMTP status code
#      $message: SMTP status message
#      \$log will be changed
sub try_rcpt_to {
  my($smtpr,$recipient,$logr)=@_;
  $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
  my $success;
  $$smtpr->to($recipient);
  if ($$smtpr->code) {
    log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
    $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
  } else {
    $success = -1;
    $$logr .= "---Connection failure---\n";
  };
  return ($success,$$smtpr->code,$$smtpr->message);
};

################################ log_smtp_reply ################################
# log result of SMTP command
# IN : \$log    : reference to the log (to be printed out via -l)
#      $code    : SMTP status code
#      @message : SMTP status message
# OUT: ---
#      \$log will be changed
sub log_smtp_reply {
  my($logr,$code,@message)=@_;
  $$logr .= sprintf('%s %s',$code,join('- ',@message));
  return;
}

############################### analyze_smtp_reply ##############################
# analyze SMTP response codes and messages
# IN : $code    : SMTP status code
#      @message : SMTP status message
# OUT: exit code (0 for false, 1 for true, -1 for tempfail)
sub analyze_smtp_reply {
  my($code,@message)=@_;
  my $type = substr($code, 0, 1);
  if ($type == 2) {
    return 1;
  } elsif ($type == 5) {
    return 0;
  } elsif ($type == 4) {
    return -1;
  };
  return -1;
}

############################## connection_failed ###############################
# print failure message and return status 1
# IN : @message : SMTP status message
# OUT: 1
sub connection_failed {
  my(@message)=@_;
  print "  ! Connection failed or other temporary failure.\n" if !($options{'q'});
  printf("    %s\n",join('    ',@message)) if @message;
  return 1;
}

__END__

################################ Documentation #################################

=head1 NAME

checkmail - check deliverability of a mail address

=head1 SYNOPSIS

B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] I<address>|B<-f> I<file>

=head1 REQUIREMENTS

=over 2

=item -

Perl 5.8 or later

=item -

File::Basename

=item -

Getopt::Std

=item -

Mail::Address I<(CPAN)>

=item -

Net::DNS I<(CPAN)>

=item -

Net::SMTP

=back

Furthermore you'll need a working DNS installation.

=head1 DESCRIPTION

checkmail checks the vailidity / deliverability of a mail address.
You may submit just one address as the last argument or a file
containing one address on each line using the B<-f> option.

=head2 Configuration

For the time being, all configuration is done in the script. You have
to set the following elements of the %config hash:

=over 4

=item B<$config{'helo'}>

The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.

=item B<$config{'from'}>

The sender address to be used for I<MAIL FROM> while testing.

=back

=head2 Usage

After configuring the script you may run your first test with

    checkmail user@example.org

B<checkmail> will try to determine the mail exchanger(s) (MX)
responsible for I<example.org> by querying the DNS for the respective
MX records and then try to connect via SMTP (on port 25) to each of
them in order of precedence (if necessary). It will run through the
SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
fall back to the I<example.org> host itself, provided there is at
least one A record defined in the DNS. If there are neither MX nor A
records for I<example.org>, mail is not deliverable and B<checkmail>
will fail accordingly. If no host can be reached, B<checkmail> will
fail, too. Finally B<checkmail> will fail if mail to the given
recipient is not accepted by the respective host.

If B<checkmail> fails, you'll not be able to deliver mail to that
address - at least not using the configured sender address and from
the host you're testing from. However, the opposite is not true: a
mail you send may still not be delivered even if a test via
B<checkmail> succeeds. The receiving entity may reject your mail after
the I<DATA> stage, due to content checking or without any special
reason, or it may even drop, filter or bounce your mail after finally
accepting it. There is no way to be sure a mail will be accepted short
of sending a real mail to the address in question.

You may, however, try to detect hosts that will happily accept any and
all recipient in the SMTP dialog and just reject your mail later on,
for example to defeat exactly the kind of check you try to do.
B<checkmail> will do that by submitting a recipient address that is
known to be invalid; if that address is accepted, too, you'll know
that you can't reliably check the validity of any address on that
host. You can force that check by using the B<-r> option.

If you don't want to see just the results of your test, you can get a
B<complete log> of the SMTP dialog by using the B<-l> option. That may be
helpful to test for temporary failure conditions.

On the other hand you may use the B<-q> option to suppress all output;
B<checkmail> will then terminate with one of the following B<exit
status>:
       
=over 4

=item B<0>

address(es) seem/seems to be valid

=item B<1>

temporary error (connection failure or temporary failure)

=item B<2>

address is invalid

=item B<3>

address cannot reliably be checked (test using B<-r> failed)

=back

You can do B<batch processing> using B<-f> and submitting a file with
one address on each line. In that case the exit status is set to the
highest value generated by testing all addresses, i.e. it is set to
B<0> if and only if no adress failed, but to B<2> if even one address
failed and to B<3> if even one addresses couldn't reliably be checked.

And finally you can B<suppress DNS lookups> for MX and A records and
just force B<checkmail> to connect to a particular host using the
B<-m> option.

B<Please note:> You shouldn't try to validate addresses while working
from a dial-up or blacklisted host. If in doubt, use the B<-l> option
to have a closer look on the SMTP dialog yourself.

=head1 OPTIONS

=over 3

=item B<-V> (version)

Print out version and copyright information on B<checkmail> and exit.

=item B<-h> (help)

Print this man page and exit.

=item B<-q> (quit)

Suppress output and just terminate with a specific exit status.

=item B<-l> (log)

Log and print out the whole SMTP dialog.

=item B<-r> (random address)

Also try a reliably invalid address to catch hosts that try undermine
address verification.

=item B<-m> I<host> (MX to use)

Force a connection to I<host> to check deliverability to that
particular host irrespective of DNS entries. For example:

    checkmail -m test.host.example user@domain.example

=item B<-f> I<file> (file)

Process all addresses from I<file> (one on each line).

=back

=head1 INSTALLATION

Just copy checkmail to some directory and get started.

You can run your first test with

    checkmail user@example.org

=head1 ENVIRONMENT

See documentation of I<Net::DNS::Resolver>.

=head1 FILES

=over 4

=item F<checkmail.pl>

The script itself.

=back

=head1 BUGS

Please report any bugs or feature request to the author or use the
bug tracker at L<http://bugs.th-h.de/>!

=head1 SEE ALSO

L<http://th-h.de/download/scripts.php> will have the current
version of this program.

This program is maintained using the Git version control system. You
may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
current development tree or browse it on the web via
L<http://code.th-h.de/?p=mail/checkmail.git>.

=head1 AUTHOR

Thomas Hochstein <thh@inter.net>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>

This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.

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