3 # checkmail Version 0.5 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 # 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 if (my $query = $resolver->query($domain,'A','IN')) {
160 print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
161 foreach my $rr ($query->answer) {
162 $targets{$rr->address} = 0;
163 $$logr .= sprintf("- %s\n",$rr->address);
165 # no A record found either; log and fail
167 print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
168 printf(" %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
174 ################################# checkaddress #################################
175 # test address for deliverability
176 # IN : $address: adress to be tested
177 # \%targets: reference to a hash containing a list of MX hosts
178 # \$log : reference to the log (to be printed out via -l)
180 # \$log will be changed
182 my ($address,$targetsr,$logr) = @_;
183 my %targets = %{$targetsr};
185 # walk %targets in order of preference
186 foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
187 printf(" / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
188 $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
189 $status = checksmtp($address,$host,$logr);
190 last if ($status != 1);
195 ################################### checksmtp ##################################
196 # connect to a remote machine on port 25 and test deliverability of a mail
197 # address by doing the SMTP dialog until RCPT TO stage
198 # IN : $address: address to test
199 # $target : target host
200 # \$log : reference to the log (to be printed out via -l)
201 # OUT: .........: reference to a hash containing a list of target hosts
202 # \$log will be changed
204 my ($address,$target,$logr) = @_;
206 # start SMTP connection
207 if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
208 $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
209 $$logr .= "EHLO $config{'helo'}\n";
210 log_smtp_reply($logr,$smtp->code,$smtp->message);
211 $smtp->mail($config{'from'});
212 $$logr .= "MAIL FROM:<$config{'from'}>\n";
213 log_smtp_reply($logr,$smtp->code,$smtp->message);
215 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
216 # connection failure?
218 $status = connection_failed(@message);
219 # delivery attempt was successful?
221 # -r: try random address (which should be guaranteed to be invalid)
223 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
224 # connection failure?
226 $status = connection_failed(@message);
227 # verification impossible?
230 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
233 # if -r is not set or status was not set to 3: valid address
234 if (!defined($status)) {
236 print " > Address is valid.\n" if !($options{'q'});
238 # delivery attempt failed?
241 print " > Address is INVALID:\n" if !($options{'q'});
242 print ' ' . join(' ',@message) if !($options{'q'});
244 # terminate SMTP connection
247 log_smtp_reply($logr,$smtp->code,$smtp->message);
249 # SMTP connection failed / timeout
250 $status = connection_failed();
251 $$logr .= "---Connection failure---\n";
256 ############################### create_rand_addr ###############################
257 # create a random mail address
258 # IN : $domain: the domain part
259 # OUT: $address: the address
260 sub create_rand_addr {
262 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
264 while (length($address) < 15) {
265 $address .= substr($allowed, (int(rand(length($allowed)))),1);
267 return ($address.'@'.$domain);
270 ################################ parse_dns_reply ###############################
271 # parse DNS response codes and return code and description
272 # IN : $response: a DNS response code
273 # OUT: "$response ($desciption)"
274 sub parse_dns_reply {
276 my %dnsrespcodes = (NOERROR => 'empty response',
277 NXDOMAIN => 'non-existent domain',
278 SERVFAIL => 'DNS server failure',
279 REFUSED => 'DNS query refused',
280 FORMERR => 'format error',
281 NOTIMP => 'not implemented');
282 if(defined($dnsrespcodes{$response})) {
283 return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
289 ############################### print_dns_result ###############################
290 # print and log result of DNS query
291 # IN : $domain: domain the DNS was queried for
292 # $type : record type (MX, A, ...)
293 # $count : number of records found
294 # $error : DNS response code
295 # \$log : reference to the log (to be printed out via -l)
297 # \$log will be changed
298 sub print_dns_result {
299 my ($domain,$type,$count,$error,$logr) = @_;
300 if (defined($count)) {
301 printf(" %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
302 $$logr .= sprintf("%s DNS record(s):\n",$type);
304 printf(" No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
305 $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
310 ################################## try_rcpt_to #################################
311 # send RCPT TO and return replies
312 # IN : \$smtp : a reference to an SMTP object
313 # $recipient: a mail address
314 # \$log : reference to the log (to be printed out via -l)
315 # OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
316 # $code : SMTP status code
317 # $message: SMTP status message
318 # \$log will be changed
320 my($smtpr,$recipient,$logr)=@_;
321 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
323 $$smtpr->to($recipient);
325 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
326 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
329 $$logr .= "---Connection failure---\n";
331 return ($success,$$smtpr->code,$$smtpr->message);
334 ################################ log_smtp_reply ################################
335 # log result of SMTP command
336 # IN : \$log : reference to the log (to be printed out via -l)
337 # $code : SMTP status code
338 # @message : SMTP status message
340 # \$log will be changed
342 my($logr,$code,@message)=@_;
343 $$logr .= sprintf('%s %s',$code,join('- ',@message));
347 ############################### analyze_smtp_reply ##############################
348 # analyze SMTP response codes and messages
349 # IN : $code : SMTP status code
350 # @message : SMTP status message
351 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
352 sub analyze_smtp_reply {
353 my($code,@message)=@_;
354 my $type = substr($code, 0, 1);
357 } elsif ($type == 5) {
359 } elsif ($type == 4) {
365 ############################## connection_failed ###############################
366 # print failure message and return status 1
367 # IN : @message : SMTP status message
369 sub connection_failed {
371 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
372 printf(" %s\n",join(' ',@message)) if @message;
378 ################################ Documentation #################################
382 checkmail - check deliverability of a mail address
386 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
406 Mail::Address I<(CPAN)>
418 Furthermore you'll need a working DNS installation.
422 checkmail checks the vailidity / deliverability of a mail address.
423 You may submit just one address as the last argument or a file
424 containing one address on each line using the B<-f> option.
428 For the time being, all configuration is done in the script. You have
429 to set the following elements of the %config hash:
433 =item B<$config{'helo'}>
435 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
437 =item B<$config{'from'}>
439 The sender address to be used for I<MAIL FROM> while testing.
443 You may override that configuration by using the B<-e> and B<-s>
444 command line options.
448 After configuring the script you may run your first test with
450 checkmail user@example.org
452 B<checkmail> will check the address for syntactic validity. If the
453 address is valid, it will try to determine the mail exchanger(s) (MX)
454 responsible for I<example.org> by querying the DNS for the respective
455 MX records and then try to connect via SMTP (on port 25) to each of
456 them in order of precedence (if necessary). It will run through the
457 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
458 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
459 fall back to the I<example.org> host itself, provided there is at
460 least one A record defined in the DNS. If there are neither MX nor A
461 records for I<example.org>, mail is not deliverable and B<checkmail>
462 will fail accordingly. If no host can be reached, B<checkmail> will
463 fail, too. Finally B<checkmail> will fail if mail to the given
464 recipient is not accepted by the respective host.
466 If B<checkmail> fails, you'll not be able to deliver mail to that
467 address - at least not using the configured sender address and from
468 the host you're testing from. However, the opposite is not true: a
469 mail you send may still not be delivered even if a test via
470 B<checkmail> succeeds. The receiving entity may reject your mail after
471 the I<DATA> stage, due to content checking or without any special
472 reason, or it may even drop, filter or bounce your mail after finally
473 accepting it. There is no way to be sure a mail will be accepted short
474 of sending a real mail to the address in question.
476 You may, however, try to detect hosts that will happily accept any and
477 all recipient in the SMTP dialog and just reject your mail later on,
478 for example to defeat exactly the kind of check you try to do.
479 B<checkmail> will do that by submitting a recipient address that is
480 known to be invalid; if that address is accepted, too, you'll know
481 that you can't reliably check the validity of any address on that
482 host. You can force that check by using the B<-r> option.
484 If you don't want to see just the results of your test, you can get a
485 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
486 helpful to test for temporary failure conditions.
488 On the other hand you may use the B<-q> option to suppress all output;
489 B<checkmail> will then terminate with one of the following B<exit
496 address(es) seem/seems to be valid
500 temporary error (connection failure or temporary failure)
508 address cannot reliably be checked (test using B<-r> failed)
512 You can do B<batch processing> using B<-f> and submitting a file with
513 one address on each line. In that case the exit status is set to the
514 highest value generated by testing all addresses, i.e. it is set to
515 B<0> if and only if no adress failed, but to B<2> if even one address
516 failed and to B<3> if even one addresses couldn't reliably be checked.
518 And finally you can B<suppress DNS lookups> for MX and A records and
519 just force B<checkmail> to connect to a particular host using the
522 B<Please note:> You shouldn't try to validate addresses while working
523 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
524 to have a closer look on the SMTP dialog yourself.
526 B<Please note:> To avoid shell expansion on addresses you submit to
527 B<checkmail>, use B<batch processing>.
533 =item B<-V> (version)
535 Print out version and copyright information on B<checkmail> and exit.
539 Print this man page and exit.
543 Suppress output and just terminate with a specific exit status.
547 Log and print out the whole SMTP dialog.
549 =item B<-r> (random address)
551 Also try a reliably invalid address to catch hosts that try undermine
552 address verification.
554 =item B<-m> I<host> (MX to use)
556 Force a connection to I<host> to check deliverability to that
557 particular host irrespective of DNS entries. For example:
559 checkmail -m test.host.example user@domain.example
561 =item B<-s> I<sender> (value for MAIL FROM)
563 Override configuration and use I<sender> for MAIL FROM.
565 =item B<-e> I<EHLO> (value for EHLO)
567 Override configuration and use I<EHLO> for EHLO.
569 =item B<-f> I<file> (file)
571 Process all addresses from I<file> (one on each line).
577 Just copy checkmail to some directory and get started.
579 You can run your first test with
581 checkmail user@example.org
585 See documentation of I<Net::DNS::Resolver>.
591 =item F<checkmail.pl>
599 Please report any bugs or feature request to the author or use the
600 bug tracker at L<http://bugs.th-h.de/>!
604 L<http://th-h.de/download/scripts.php> will have the current
605 version of this program.
607 This program is maintained using the Git version control system. You
608 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
609 current development tree or browse it on the web via
610 L<http://code.th-h.de/?p=mail/checkmail.git>.
614 Thomas Hochstein <thh@inter.net>
616 =head1 COPYRIGHT AND LICENSE
618 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
620 This program is free software; you may redistribute it and/or modify it
621 under the same terms as Perl itself.