3 # checkmail Version 0.6.1 by Thomas Hochstein
5 # This script tries to verify the deliverability of (a) mail address(es).
7 # Copyright (c) 2002-2011 Thomas Hochstein <thh@inter.net>
9 # It can be redistributed and/or modified under the same terms under
10 # which Perl itself is published.
12 our $VERSION = "0.6.2";
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-2016 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 defined($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 # regexp taken from http://www.regular-expressions.info/email.html
96 # with escaping of "/" added two times and "*" changed to "+"
97 # in localpart, second alternative
98 if ($address !~ /^(?:[a-z0-9!#$%&'*+\/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+\/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f]+)")@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i) {
99 printf(" > Address <%s> is syntactically INVALID.\n",$address) if !($options{'q'});
102 my $domain = Mail::Address->new('',$address)->host;
103 printf(" * Testing %s ...\n",$address) if !($options{'q'});
104 $log .= "\n===== BEGIN $address =====\n";
105 # get list of target hosts or take host forced via -m
106 if (!$options{'m'}) {
107 %targets = %{gettargets($domain,\$log)};
109 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
111 print " $message" if !($options{'q'});
112 # just one target host with preference 0
113 $targets{$options{'m'}} = 0;
116 $curstat = checkaddress($address,\%targets,\$log);
119 $message = 'DNS lookup failure';
120 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
121 $log .= $message . '.';
123 $log .= "====== END $address ======\n";
125 $status = $curstat if (!defined($status) or $curstat > $status);
128 print $log if ($options{'l'});
130 # status 0: valid / batch processing
131 # 1: connection failed or temporary failure
134 #D print "\n-> EXIT $status\n";
137 ################################## gettargets ##################################
138 # get mail exchanger(s) or A record(s) for a domain
139 # IN : $domain: domain to query the DNS for
140 # OUT: \%targets: reference to a hash containing a list of target hosts
142 my ($domain,$logr) = @_;
144 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
147 # get MX record(s) as a list sorted by preference
148 if (my @mxrr = mx($resolver,$domain)) {
149 print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
150 foreach my $rr (@mxrr) {
151 $targets{$rr->exchange} = $rr->preference;
152 $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
154 # no MX record found; log and try A record(s)
156 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
157 print(" Falling back to A record ...\n") if !($options{'q'});
159 # may get CNAMEs instead ...
160 if (my $query = $resolver->query($domain,'A','IN')) {
161 # save number of answers in a counter
162 my $acount = $query->header->ancount;
163 foreach my $rr ($query->answer) {
164 if ($rr->type ne 'A') {
165 # decrease counter if it's not an A record
167 # report CNAMEs and don't add them to target list
168 if ($rr->type eq 'CNAME') {
169 printf (" ~ '%s' is a CNAME for '%s' and will be resolved accordingly. \n",$rr->name,$rr->cname) if !($options{'q'});
170 $$logr .= sprintf("CNAME resolved: %s -> %s\n",$rr->name,$rr->cname);
174 $targets{$rr->address} = 0;
175 $$logr .= sprintf("- %s\n",$rr->address);
177 print_dns_result($domain,'A',$acount,undef,$logr);
178 # no A record found either; log and fail
180 print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
181 printf(" %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
187 ################################# checkaddress #################################
188 # test address for deliverability
189 # IN : $address: adress to be tested
190 # \%targets: reference to a hash containing a list of MX hosts
191 # \$log : reference to the log (to be printed out via -l)
193 # \$log will be changed
195 my ($address,$targetsr,$logr) = @_;
196 my %targets = %{$targetsr};
198 # walk %targets in order of preference
199 foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
200 printf(" / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
201 $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
202 $status = checksmtp($address,$host,$logr);
203 last if ($status != 1);
208 ################################### checksmtp ##################################
209 # connect to a remote machine on port 25 and test deliverability of a mail
210 # address by doing the SMTP dialog until RCPT TO stage
211 # IN : $address: address to test
212 # $target : target host
213 # \$log : reference to the log (to be printed out via -l)
214 # OUT: .........: reference to a hash containing a list of target hosts
215 # \$log will be changed
217 my ($address,$target,$logr) = @_;
219 # start SMTP connection
220 if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
221 $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
222 $$logr .= "EHLO $config{'helo'}\n";
223 log_smtp_reply($logr,$smtp->code,$smtp->message);
224 $smtp->mail($config{'from'});
225 $$logr .= "MAIL FROM:<$config{'from'}>\n";
226 log_smtp_reply($logr,$smtp->code,$smtp->message);
228 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
229 # connection failure?
231 $status = connection_failed(@message);
232 # delivery attempt was successful?
234 # -r: try random address (which should be guaranteed to be invalid)
236 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
237 # connection failure?
239 $status = connection_failed(@message);
240 # reset status - the address has been checked and _is_ valid!
242 print " > Address verification currently impossible. You'll have to try again or send a test mail ...\n" if !($options{'q'});
243 # verification impossible?
246 print " > Address verification impossible. You'll have to send a test mail ...\n" if !($options{'q'});
249 # if -r is not set or status was not set to 3: valid address
250 if (!defined($status)) {
252 print " > Address is valid.\n" if !($options{'q'});
254 # delivery attempt failed?
257 print " > Address is INVALID:\n" if !($options{'q'});
258 print ' ' . join(' ',@message) if !($options{'q'});
260 # terminate SMTP connection
263 log_smtp_reply($logr,$smtp->code,$smtp->message);
265 # SMTP connection failed / timeout
266 $status = connection_failed();
267 $$logr .= "---Connection failure---\n";
272 ############################### create_rand_addr ###############################
273 # create a random mail address
274 # IN : $domain: the domain part
275 # OUT: $address: the address
276 sub create_rand_addr {
278 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
280 while (length($address) < 15) {
281 $address .= substr($allowed, (int(rand(length($allowed)))),1);
283 return ($address.'@'.$domain);
286 ################################ parse_dns_reply ###############################
287 # parse DNS response codes and return code and description
288 # IN : $response: a DNS response code
289 # OUT: "$response ($desciption)"
290 sub parse_dns_reply {
292 my %dnsrespcodes = (NOERROR => 'empty response',
293 NXDOMAIN => 'non-existent domain',
294 SERVFAIL => 'DNS server failure',
295 REFUSED => 'DNS query refused',
296 FORMERR => 'format error',
297 NOTIMP => 'not implemented');
298 if(defined($dnsrespcodes{$response})) {
299 return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
305 ############################### print_dns_result ###############################
306 # print and log result of DNS query
307 # IN : $domain: domain the DNS was queried for
308 # $type : record type (MX, A, ...)
309 # $count : number of records found
310 # $error : DNS response code
311 # \$log : reference to the log (to be printed out via -l)
313 # \$log will be changed
314 sub print_dns_result {
315 my ($domain,$type,$count,$error,$logr) = @_;
316 if (defined($count)) {
317 printf(" %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
318 $$logr .= sprintf("%s DNS record(s):\n",$type);
320 printf(" No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
321 $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
326 ################################## try_rcpt_to #################################
327 # send RCPT TO and return replies
328 # IN : \$smtp : a reference to an SMTP object
329 # $recipient: a mail address
330 # \$log : reference to the log (to be printed out via -l)
331 # OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
332 # $code : SMTP status code
333 # $message: SMTP status message
334 # \$log will be changed
336 my($smtpr,$recipient,$logr)=@_;
337 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
339 $$smtpr->to($recipient);
341 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
342 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
345 $$logr .= "---Connection failure---\n";
347 return ($success,$$smtpr->code,$$smtpr->message);
350 ################################ log_smtp_reply ################################
351 # log result of SMTP command
352 # IN : \$log : reference to the log (to be printed out via -l)
353 # $code : SMTP status code
354 # @message : SMTP status message
356 # \$log will be changed
358 my($logr,$code,@message)=@_;
359 $$logr .= sprintf('%s %s',$code,join('- ',@message));
363 ############################### analyze_smtp_reply ##############################
364 # analyze SMTP response codes and messages
365 # IN : $code : SMTP status code
366 # @message : SMTP status message
367 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
368 sub analyze_smtp_reply {
369 my($code,@message)=@_;
370 my $type = substr($code, 0, 1);
373 } elsif ($type == 5) {
375 } elsif ($type == 4) {
381 ############################## connection_failed ###############################
382 # print failure message and return status 1
383 # IN : @message : SMTP status message
385 sub connection_failed {
387 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
388 printf(" %s\n",join(' ',@message)) if @message;
394 ################################ Documentation #################################
398 checkmail - check deliverability of a mail address
402 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
422 Mail::Address I<(CPAN)>
434 Furthermore you'll need a working DNS installation.
438 checkmail checks the vailidity / deliverability of a mail address.
439 You may submit just one address as the last argument or a file
440 containing one address on each line using the B<-f> option.
444 For the time being, all configuration is done in the script. You have
445 to set the following elements of the %config hash:
449 =item B<$config{'helo'}>
451 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
453 =item B<$config{'from'}>
455 The sender address to be used for I<MAIL FROM> while testing.
456 May be empty ('') to set '<>' as MAIL FROM.
460 You may override that configuration by using the B<-e> and B<-s>
461 command line options.
465 After configuring the script you may run your first test with
467 checkmail user@example.org
469 B<checkmail> will check the address for syntactic validity. If the
470 address is valid, it will try to determine the mail exchanger(s) (MX)
471 responsible for I<example.org> by querying the DNS for the respective
472 MX records and then try to connect via SMTP (on port 25) to each of
473 them in order of precedence (if necessary). It will run through the
474 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
475 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
476 fall back to the I<example.org> host itself, provided there is at
477 least one A record defined in the DNS. CNAMEs will be accepted and
478 resolved here. If there are neither MX nor A records for
479 I<example.org>, mail is not deliverable and B<checkmail> will fail
480 accordingly. If no host can be reached, B<checkmail> will fail,
481 too. Finally B<checkmail> will fail if mail to the given recipient
482 is not accepted by the respective host.
484 If B<checkmail> fails, you'll not be able to deliver mail to that
485 address - at least not using the configured sender address and from
486 the host you're testing from. However, the opposite is not true: a
487 mail you send may still not be delivered even if a test via
488 B<checkmail> succeeds. The receiving entity may reject your mail after
489 the I<DATA> stage, due to content checking or without any special
490 reason, or it may even drop, filter or bounce your mail after finally
491 accepting it. There is no way to be sure a mail will be accepted short
492 of sending a real mail to the address in question.
494 You may, however, try to detect hosts that will happily accept any and
495 all recipient in the SMTP dialog and just reject your mail later on,
496 for example to defeat exactly the kind of check you try to do.
497 B<checkmail> will do that by submitting a recipient address that is
498 known to be invalid; if that address is accepted, too, you'll know
499 that you can't reliably check the validity of any address on that
500 host. You can force that check by using the B<-r> option.
502 If you don't want to see just the results of your test, you can get a
503 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
504 helpful to test for temporary failure conditions.
506 On the other hand you may use the B<-q> option to suppress all output;
507 B<checkmail> will then terminate with one of the following B<exit
514 address(es) seem/seems to be valid
518 temporary error (connection failure or temporary failure)
526 address cannot reliably be checked (test using B<-r> failed)
530 You can do B<batch processing> using B<-f> and submitting a file with
531 one address on each line. In that case the exit status is set to the
532 highest value generated by testing all addresses, i.e. it is set to
533 B<0> if and only if no adress failed, but to B<2> if even one address
534 failed and to B<3> if even one addresses couldn't reliably be checked.
536 And finally you can B<suppress DNS lookups> for MX and A records and
537 just force B<checkmail> to connect to a particular host using the
540 B<Please note:> You shouldn't try to validate addresses while working
541 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
542 to have a closer look on the SMTP dialog yourself.
544 B<Please note:> To avoid shell expansion on addresses you submit to
545 B<checkmail>, use B<batch processing>.
551 =item B<-V> (version)
553 Print out version and copyright information on B<checkmail> and exit.
557 Print this man page and exit.
561 Suppress output and just terminate with a specific exit status.
565 Log and print out the whole SMTP dialog.
567 =item B<-r> (random address)
569 Also try a reliably invalid address to catch hosts that try undermine
570 address verification.
572 =item B<-m> I<host> (MX to use)
574 Force a connection to I<host> to check deliverability to that
575 particular host irrespective of DNS entries. For example:
577 checkmail -m test.host.example user@domain.example
579 =item B<-s> I<sender> (value for MAIL FROM)
581 Override configuration and use I<sender> for MAIL FROM.
583 =item B<-e> I<EHLO> (value for EHLO)
585 Override configuration and use I<EHLO> for EHLO.
587 =item B<-f> I<file> (file)
589 Process all addresses from I<file> (one on each line).
595 Just copy checkmail to some directory and get started.
597 You can run your first test with
599 checkmail user@example.org
603 See documentation of I<Net::DNS::Resolver>.
609 =item F<checkmail.pl>
617 Please report any bugs or feature request to the author or use the
618 bug tracker at L<http://bugs.th-h.de/>!
622 L<http://th-h.de/download/scripts.php> will have the current
623 version of this program.
625 This program is maintained using the Git version control system. You
626 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
627 current development tree or browse it on the web via
628 L<http://code.th-h.de/?p=mail/checkmail.git>.
632 Thomas Hochstein <thh@inter.net>
634 =head1 COPYRIGHT AND LICENSE
636 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
638 This program is free software; you may redistribute it and/or modify it
639 under the same terms as Perl itself.