3 # checkmail Version 0.4 by Thomas Hochstein
5 # This script tries to verify the deliverability of (a) mail address(es).
7 # Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
9 # It can be redistributed and/or modified under the same terms under
10 # which Perl itself is published.
14 ################################# Configuration ################################
15 # Please fill in a working configuration!
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'
23 ################################### Modules ####################################
31 ################################# Main program #################################
33 $Getopt::Std::STANDARD_HELP_VERSION = 1;
34 my $myself = basename($0);
36 # read commandline options
38 getopts('Vhqlrf:m:s:e:', \%options);
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";
47 # -h: feed myself to perldoc
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";
69 # -s / -e: override configuration
70 $config{'from'} = $options{'s'} if $options{'s'};
71 $config{'helo'} = $options{'e'} if $options{'e'};
73 # -f: open file and read addresses to @adresses
76 if (-e $options{'f'}) {
77 open FILE, "<$options{'f'}" or die("$myself ERROR: Could not open file $options{'f'} for reading: $!");
79 die("$myself ERROR: File $options{'f'} does not exist!\n");
86 # fill @adresses with single address to check
88 push(@addresses,$ARGV[0]);
91 # loop over each address and test it
92 my (%targets,$curstat,$status,$log,$message);
93 foreach (@addresses) {
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
100 %targets = %{gettargets($domain,\$log)};
102 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
104 print " $message" if !($options{'q'});
105 # just one target host with preference 0
106 $targets{$options{'m'}} = 0;
109 $curstat = checkaddress($address,\%targets,\$log);
112 $message = 'DNS lookup failure';
113 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
114 $log .= $message . '.';
116 $log .= "====== END $address ======\n";
117 $status = $curstat if (!defined($status) or $curstat > $status);
120 print $log if ($options{'l'});
122 # status 0: valid / batch processing
123 # 1: connection failed or temporary failure
126 #D print "\n-> EXIT $status\n";
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
134 my ($domain,$logr) = @_;
136 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
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);
146 # no MX record found; log and try A record(s)
148 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
149 print(" Falling back to A record ...\n") if !($options{'q'});
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);
157 # no A record found either; log and fail
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'});
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)
172 # \$log will be changed
174 my ($address,$targetsr,$logr) = @_;
175 my %targets = %{$targetsr};
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);
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
196 my ($address,$target,$logr) = @_;
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);
207 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
208 # connection failure?
210 $status = connection_failed(@message);
211 # delivery attempt was successful?
213 # -r: try random address (which should be guaranteed to be invalid)
215 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
216 # connection failure?
218 $status = connection_failed(@message);
219 # verification impossible?
222 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
225 # if -r is not set or status was not set to 3: valid address
226 if (!defined($status)) {
228 print " > Address is valid.\n" if !($options{'q'});
230 # delivery attempt failed?
233 print " > Address is INVALID:\n" if !($options{'q'});
234 print ' ' . join(' ',@message) if !($options{'q'});
236 # terminate SMTP connection
239 log_smtp_reply($logr,$smtp->code,$smtp->message);
241 # SMTP connection failed / timeout
242 $status = connection_failed();
243 $$logr .= "---Connection failure---\n";
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 {
254 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
256 while (length($address) < 15) {
257 $address .= substr($allowed, (int(rand(length($allowed)))),1);
259 return ($address.'@'.$domain);
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 {
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});
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)
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);
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));
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
312 my($smtpr,$recipient,$logr)=@_;
313 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
315 $$smtpr->to($recipient);
317 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
318 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
321 $$logr .= "---Connection failure---\n";
323 return ($success,$$smtpr->code,$$smtpr->message);
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
332 # \$log will be changed
334 my($logr,$code,@message)=@_;
335 $$logr .= sprintf('%s %s',$code,join('- ',@message));
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);
349 } elsif ($type == 5) {
351 } elsif ($type == 4) {
357 ############################## connection_failed ###############################
358 # print failure message and return status 1
359 # IN : @message : SMTP status message
361 sub connection_failed {
363 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
364 printf(" %s\n",join(' ',@message)) if @message;
370 ################################ Documentation #################################
374 checkmail - check deliverability of a mail address
378 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
398 Mail::Address I<(CPAN)>
410 Furthermore you'll need a working DNS installation.
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.
420 For the time being, all configuration is done in the script. You have
421 to set the following elements of the %config hash:
425 =item B<$config{'helo'}>
427 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
429 =item B<$config{'from'}>
431 The sender address to be used for I<MAIL FROM> while testing.
435 You may override that configuration by using the B<-e> and B<-s>
436 command line options.
440 After configuring the script you may run your first test with
442 checkmail user@example.org
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.
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.
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.
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.
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
487 address(es) seem/seems to be valid
491 temporary error (connection failure or temporary failure)
499 address cannot reliably be checked (test using B<-r> failed)
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.
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
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.
517 B<Please note:> To avoid shell expansion on addresses you submit to
518 B<checkmail>, use B<batch processing>.
524 =item B<-V> (version)
526 Print out version and copyright information on B<checkmail> and exit.
530 Print this man page and exit.
534 Suppress output and just terminate with a specific exit status.
538 Log and print out the whole SMTP dialog.
540 =item B<-r> (random address)
542 Also try a reliably invalid address to catch hosts that try undermine
543 address verification.
545 =item B<-m> I<host> (MX to use)
547 Force a connection to I<host> to check deliverability to that
548 particular host irrespective of DNS entries. For example:
550 checkmail -m test.host.example user@domain.example
552 =item B<-s> I<sender> (value for MAIL FROM)
554 Override configuration and use I<sender> for MAIL FROM.
556 =item B<-e> I<EHLO> (value for EHLO)
558 Override configuration and use I<EHLO> for EHLO.
560 =item B<-f> I<file> (file)
562 Process all addresses from I<file> (one on each line).
568 Just copy checkmail to some directory and get started.
570 You can run your first test with
572 checkmail user@example.org
576 See documentation of I<Net::DNS::Resolver>.
582 =item F<checkmail.pl>
590 Please report any bugs or feature request to the author or use the
591 bug tracker at L<http://bugs.th-h.de/>!
595 L<http://th-h.de/download/scripts.php> will have the current
596 version of this program.
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>.
605 Thomas Hochstein <thh@inter.net>
607 =head1 COPYRIGHT AND LICENSE
609 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
611 This program is free software; you may redistribute it and/or modify it
612 under the same terms as Perl itself.