[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',
            # a syntactically valid "random" - reliably not existing - localpart
            rand => 'ZOq62fow1i'
           );

################################### Modules ####################################
use strict;
use File::Basename;
use Getopt::Std;
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 = $_;
  (undef,my $domain) = splitaddress($address);
  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();
    # delivery attempt was successful?
    } elsif ($success) {
      # -r: try random address (which should be guaranteed to be invalid)
      if ($options{'r'}) {
        (undef,my $domain) = splitaddress($address);
        my ($success,$code,@message) = try_rcpt_to(\$smtp,$config{'rand'}.'@'.$domain,$logr);
        # connection failure?
        if ($success < 0) {
          $status = connection_failed();
        # 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;
}

################################# splitaddress #################################
# split mail address into local and domain part
# IN : $address: a mail address
# OUT: $local : local part
#      $domain: domain part
sub splitaddress {
  my($address)=@_;
  (my $lp = $address) =~ s/^([^@]+)@.*/$1/;
  (my $domain = $address) =~ s/[^@]+\@(\S*)$/$1/;
  return ($lp,$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: true or false
#      $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);
  } 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;
}

############################## connection_failed ###############################
# print failure message and return status 1
# OUT: 1
sub connection_failed {
  print "  > Connection failure.\n" if !($options{'q'});
  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 -

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.

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

A "random" local part to construct a reliably invalid address for use
with the B<-r> option.

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