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 # and escaping of "/" added two times
97 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) {
98 printf(" > Address <%s> is syntactically INVALID.\n",$address) if !($options{'q'});
101 my $domain = Mail::Address->new('',$address)->host;
102 printf(" * Testing %s ...\n",$address) if !($options{'q'});
103 $log .= "\n===== BEGIN $address =====\n";
104 # get list of target hosts or take host forced via -m
105 if (!$options{'m'}) {
106 %targets = %{gettargets($domain,\$log)};
108 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
110 print " $message" if !($options{'q'});
111 # just one target host with preference 0
112 $targets{$options{'m'}} = 0;
115 $curstat = checkaddress($address,\%targets,\$log);
118 $message = 'DNS lookup failure';
119 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
120 $log .= $message . '.';
122 $log .= "====== END $address ======\n";
124 $status = $curstat if (!defined($status) or $curstat > $status);
127 print $log if ($options{'l'});
129 # status 0: valid / batch processing
130 # 1: connection failed or temporary failure
133 #D print "\n-> EXIT $status\n";
136 ################################## gettargets ##################################
137 # get mail exchanger(s) or A record(s) for a domain
138 # IN : $domain: domain to query the DNS for
139 # OUT: \%targets: reference to a hash containing a list of target hosts
141 my ($domain,$logr) = @_;
143 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
146 # get MX record(s) as a list sorted by preference
147 if (my @mxrr = mx($resolver,$domain)) {
148 print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
149 foreach my $rr (@mxrr) {
150 $targets{$rr->exchange} = $rr->preference;
151 $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
153 # no MX record found; log and try A record(s)
155 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
156 print(" Falling back to A record ...\n") if !($options{'q'});
158 if (my $query = $resolver->query($domain,'A','IN')) {
159 print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
160 foreach my $rr ($query->answer) {
161 $targets{$rr->address} = 0;
162 $$logr .= sprintf("- %s\n",$rr->address);
164 # no A record found either; log and fail
166 print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
167 printf(" %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
173 ################################# checkaddress #################################
174 # test address for deliverability
175 # IN : $address: adress to be tested
176 # \%targets: reference to a hash containing a list of MX hosts
177 # \$log : reference to the log (to be printed out via -l)
179 # \$log will be changed
181 my ($address,$targetsr,$logr) = @_;
182 my %targets = %{$targetsr};
184 # walk %targets in order of preference
185 foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
186 printf(" / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
187 $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
188 $status = checksmtp($address,$host,$logr);
189 last if ($status != 1);
194 ################################### checksmtp ##################################
195 # connect to a remote machine on port 25 and test deliverability of a mail
196 # address by doing the SMTP dialog until RCPT TO stage
197 # IN : $address: address to test
198 # $target : target host
199 # \$log : reference to the log (to be printed out via -l)
200 # OUT: .........: reference to a hash containing a list of target hosts
201 # \$log will be changed
203 my ($address,$target,$logr) = @_;
205 # start SMTP connection
206 if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
207 $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
208 $$logr .= "EHLO $config{'helo'}\n";
209 log_smtp_reply($logr,$smtp->code,$smtp->message);
210 $smtp->mail($config{'from'});
211 $$logr .= "MAIL FROM:<$config{'from'}>\n";
212 log_smtp_reply($logr,$smtp->code,$smtp->message);
214 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
215 # connection failure?
217 $status = connection_failed(@message);
218 # delivery attempt was successful?
220 # -r: try random address (which should be guaranteed to be invalid)
222 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
223 # connection failure?
225 $status = connection_failed(@message);
226 # verification impossible?
229 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
232 # if -r is not set or status was not set to 3: valid address
233 if (!defined($status)) {
235 print " > Address is valid.\n" if !($options{'q'});
237 # delivery attempt failed?
240 print " > Address is INVALID:\n" if !($options{'q'});
241 print ' ' . join(' ',@message) if !($options{'q'});
243 # terminate SMTP connection
246 log_smtp_reply($logr,$smtp->code,$smtp->message);
248 # SMTP connection failed / timeout
249 $status = connection_failed();
250 $$logr .= "---Connection failure---\n";
255 ############################### create_rand_addr ###############################
256 # create a random mail address
257 # IN : $domain: the domain part
258 # OUT: $address: the address
259 sub create_rand_addr {
261 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
263 while (length($address) < 15) {
264 $address .= substr($allowed, (int(rand(length($allowed)))),1);
266 return ($address.'@'.$domain);
269 ################################ parse_dns_reply ###############################
270 # parse DNS response codes and return code and description
271 # IN : $response: a DNS response code
272 # OUT: "$response ($desciption)"
273 sub parse_dns_reply {
275 my %dnsrespcodes = (NOERROR => 'empty response',
276 NXDOMAIN => 'non-existent domain',
277 SERVFAIL => 'DNS server failure',
278 REFUSED => 'DNS query refused',
279 FORMERR => 'format error',
280 NOTIMP => 'not implemented');
281 if(defined($dnsrespcodes{$response})) {
282 return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
288 ############################### print_dns_result ###############################
289 # print and log result of DNS query
290 # IN : $domain: domain the DNS was queried for
291 # $type : record type (MX, A, ...)
292 # $count : number of records found
293 # $error : DNS response code
294 # \$log : reference to the log (to be printed out via -l)
296 # \$log will be changed
297 sub print_dns_result {
298 my ($domain,$type,$count,$error,$logr) = @_;
299 if (defined($count)) {
300 printf(" %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
301 $$logr .= sprintf("%s DNS record(s):\n",$type);
303 printf(" No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
304 $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
309 ################################## try_rcpt_to #################################
310 # send RCPT TO and return replies
311 # IN : \$smtp : a reference to an SMTP object
312 # $recipient: a mail address
313 # \$log : reference to the log (to be printed out via -l)
314 # OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
315 # $code : SMTP status code
316 # $message: SMTP status message
317 # \$log will be changed
319 my($smtpr,$recipient,$logr)=@_;
320 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
322 $$smtpr->to($recipient);
324 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
325 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
328 $$logr .= "---Connection failure---\n";
330 return ($success,$$smtpr->code,$$smtpr->message);
333 ################################ log_smtp_reply ################################
334 # log result of SMTP command
335 # IN : \$log : reference to the log (to be printed out via -l)
336 # $code : SMTP status code
337 # @message : SMTP status message
339 # \$log will be changed
341 my($logr,$code,@message)=@_;
342 $$logr .= sprintf('%s %s',$code,join('- ',@message));
346 ############################### analyze_smtp_reply ##############################
347 # analyze SMTP response codes and messages
348 # IN : $code : SMTP status code
349 # @message : SMTP status message
350 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
351 sub analyze_smtp_reply {
352 my($code,@message)=@_;
353 my $type = substr($code, 0, 1);
356 } elsif ($type == 5) {
358 } elsif ($type == 4) {
364 ############################## connection_failed ###############################
365 # print failure message and return status 1
366 # IN : @message : SMTP status message
368 sub connection_failed {
370 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
371 printf(" %s\n",join(' ',@message)) if @message;
377 ################################ Documentation #################################
381 checkmail - check deliverability of a mail address
385 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
405 Mail::Address I<(CPAN)>
417 Furthermore you'll need a working DNS installation.
421 checkmail checks the vailidity / deliverability of a mail address.
422 You may submit just one address as the last argument or a file
423 containing one address on each line using the B<-f> option.
427 For the time being, all configuration is done in the script. You have
428 to set the following elements of the %config hash:
432 =item B<$config{'helo'}>
434 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
436 =item B<$config{'from'}>
438 The sender address to be used for I<MAIL FROM> while testing.
442 You may override that configuration by using the B<-e> and B<-s>
443 command line options.
447 After configuring the script you may run your first test with
449 checkmail user@example.org
451 B<checkmail> will check the address for syntactic validity. If the
452 address is valid, it will try to determine the mail exchanger(s) (MX)
453 responsible for I<example.org> by querying the DNS for the respective
454 MX records and then try to connect via SMTP (on port 25) to each of
455 them in order of precedence (if necessary). It will run through the
456 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
457 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
458 fall back to the I<example.org> host itself, provided there is at
459 least one A record defined in the DNS. If there are neither MX nor A
460 records for I<example.org>, mail is not deliverable and B<checkmail>
461 will fail accordingly. If no host can be reached, B<checkmail> will
462 fail, too. Finally B<checkmail> will fail if mail to the given
463 recipient is not accepted by the respective host.
465 If B<checkmail> fails, you'll not be able to deliver mail to that
466 address - at least not using the configured sender address and from
467 the host you're testing from. However, the opposite is not true: a
468 mail you send may still not be delivered even if a test via
469 B<checkmail> succeeds. The receiving entity may reject your mail after
470 the I<DATA> stage, due to content checking or without any special
471 reason, or it may even drop, filter or bounce your mail after finally
472 accepting it. There is no way to be sure a mail will be accepted short
473 of sending a real mail to the address in question.
475 You may, however, try to detect hosts that will happily accept any and
476 all recipient in the SMTP dialog and just reject your mail later on,
477 for example to defeat exactly the kind of check you try to do.
478 B<checkmail> will do that by submitting a recipient address that is
479 known to be invalid; if that address is accepted, too, you'll know
480 that you can't reliably check the validity of any address on that
481 host. You can force that check by using the B<-r> option.
483 If you don't want to see just the results of your test, you can get a
484 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
485 helpful to test for temporary failure conditions.
487 On the other hand you may use the B<-q> option to suppress all output;
488 B<checkmail> will then terminate with one of the following B<exit
495 address(es) seem/seems to be valid
499 temporary error (connection failure or temporary failure)
507 address cannot reliably be checked (test using B<-r> failed)
511 You can do B<batch processing> using B<-f> and submitting a file with
512 one address on each line. In that case the exit status is set to the
513 highest value generated by testing all addresses, i.e. it is set to
514 B<0> if and only if no adress failed, but to B<2> if even one address
515 failed and to B<3> if even one addresses couldn't reliably be checked.
517 And finally you can B<suppress DNS lookups> for MX and A records and
518 just force B<checkmail> to connect to a particular host using the
521 B<Please note:> You shouldn't try to validate addresses while working
522 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
523 to have a closer look on the SMTP dialog yourself.
525 B<Please note:> To avoid shell expansion on addresses you submit to
526 B<checkmail>, use B<batch processing>.
532 =item B<-V> (version)
534 Print out version and copyright information on B<checkmail> and exit.
538 Print this man page and exit.
542 Suppress output and just terminate with a specific exit status.
546 Log and print out the whole SMTP dialog.
548 =item B<-r> (random address)
550 Also try a reliably invalid address to catch hosts that try undermine
551 address verification.
553 =item B<-m> I<host> (MX to use)
555 Force a connection to I<host> to check deliverability to that
556 particular host irrespective of DNS entries. For example:
558 checkmail -m test.host.example user@domain.example
560 =item B<-s> I<sender> (value for MAIL FROM)
562 Override configuration and use I<sender> for MAIL FROM.
564 =item B<-e> I<EHLO> (value for EHLO)
566 Override configuration and use I<EHLO> for EHLO.
568 =item B<-f> I<file> (file)
570 Process all addresses from I<file> (one on each line).
576 Just copy checkmail to some directory and get started.
578 You can run your first test with
580 checkmail user@example.org
584 See documentation of I<Net::DNS::Resolver>.
590 =item F<checkmail.pl>
598 Please report any bugs or feature request to the author or use the
599 bug tracker at L<http://bugs.th-h.de/>!
603 L<http://th-h.de/download/scripts.php> will have the current
604 version of this program.
606 This program is maintained using the Git version control system. You
607 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
608 current development tree or browse it on the web via
609 L<http://code.th-h.de/?p=mail/checkmail.git>.
613 Thomas Hochstein <thh@inter.net>
615 =head1 COPYRIGHT AND LICENSE
617 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
619 This program is free software; you may redistribute it and/or modify it
620 under the same terms as Perl itself.