3 # checkmail Version 0.3 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:', \%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>] <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 " <address> mail address to check\n\n";
63 print " -f <file> parse file (one address per line)\n";
67 # -f: open file and read addresses to @adresses
70 if (-e $options{'f'}) {
71 open FILE, "<$options{'f'}" or die("$myself ERROR: Could not open file $options{'f'} for reading: $!");
73 die("$myself ERROR: File $options{'f'} does not exist!\n");
80 # fill @adresses with single address to check
82 push(@addresses,$ARGV[0]);
85 # loop over each address and test it
86 my (%targets,$curstat,$status,$log,$message);
87 foreach (@addresses) {
89 my $domain = Mail::Address->new('',$address)->host;
90 printf(" * Testing %s ...\n",$address) if !($options{'q'});
91 $log .= "\n===== BEGIN $address =====\n";
92 # get list of target hosts or take host forced via -m
94 %targets = %{gettargets($domain,\$log)};
96 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
98 print " $message" if !($options{'q'});
99 # just one target host with preference 0
100 $targets{$options{'m'}} = 0;
103 $curstat = checkaddress($address,\%targets,\$log);
106 $message = 'DNS lookup failure';
107 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
108 $log .= $message . '.';
110 $log .= "====== END $address ======\n";
111 $status = $curstat if (!defined($status) or $curstat > $status);
114 print $log if ($options{'l'});
116 # status 0: valid / batch processing
117 # 1: connection failed or temporary failure
120 #D print "\n-> EXIT $status\n";
123 ################################## gettargets ##################################
124 # get mail exchanger(s) or A record(s) for a domain
125 # IN : $domain: domain to query the DNS for
126 # OUT: \%targets: reference to a hash containing a list of target hosts
128 my ($domain,$logr) = @_;
130 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
133 # get MX record(s) as a list sorted by preference
134 if (my @mxrr = mx($resolver,$domain)) {
135 print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
136 foreach my $rr (@mxrr) {
137 $targets{$rr->exchange} = $rr->preference;
138 $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
140 # no MX record found; log and try A record(s)
142 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
143 print(" Falling back to A record ...\n") if !($options{'q'});
145 if (my $query = $resolver->query($domain,'A','IN')) {
146 print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
147 foreach my $rr ($query->answer) {
148 $targets{$rr->address} = 0;
149 $$logr .= sprintf("- %s\n",$rr->address);
151 # no A record found either; log and fail
153 print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
154 printf(" %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
160 ################################# checkaddress #################################
161 # test address for deliverability
162 # IN : $address: adress to be tested
163 # \%targets: reference to a hash containing a list of MX hosts
164 # \$log : reference to the log (to be printed out via -l)
166 # \$log will be changed
168 my ($address,$targetsr,$logr) = @_;
169 my %targets = %{$targetsr};
171 # walk %targets in order of preference
172 foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
173 printf(" / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
174 $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
175 $status = checksmtp($address,$host,$logr);
176 last if ($status != 1);
181 ################################### checksmtp ##################################
182 # connect to a remote machine on port 25 and test deliverability of a mail
183 # address by doing the SMTP dialog until RCPT TO stage
184 # IN : $address: address to test
185 # $target : target host
186 # \$log : reference to the log (to be printed out via -l)
187 # OUT: .........: reference to a hash containing a list of target hosts
188 # \$log will be changed
190 my ($address,$target,$logr) = @_;
192 # start SMTP connection
193 if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
194 $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
195 $$logr .= "EHLO $config{'helo'}\n";
196 log_smtp_reply($logr,$smtp->code,$smtp->message);
197 $smtp->mail($config{'from'});
198 $$logr .= "MAIL FROM:<$config{'from'}>\n";
199 log_smtp_reply($logr,$smtp->code,$smtp->message);
201 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
202 # connection failure?
204 $status = connection_failed(@message);
205 # delivery attempt was successful?
207 # -r: try random address (which should be guaranteed to be invalid)
209 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
210 # connection failure?
212 $status = connection_failed(@message);
213 # verification impossible?
216 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
219 # if -r is not set or status was not set to 3: valid address
220 if (!defined($status)) {
222 print " > Address is valid.\n" if !($options{'q'});
224 # delivery attempt failed?
227 print " > Address is INVALID:\n" if !($options{'q'});
228 print ' ' . join(' ',@message) if !($options{'q'});
230 # terminate SMTP connection
233 log_smtp_reply($logr,$smtp->code,$smtp->message);
235 # SMTP connection failed / timeout
236 $status = connection_failed();
237 $$logr .= "---Connection failure---\n";
242 ############################### create_rand_addr ###############################
243 # create a random mail address
244 # IN : $domain: the domain part
245 # OUT: $address: the address
246 sub create_rand_addr {
248 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
250 while (length($address) < 15) {
251 $address .= substr($allowed, (int(rand(length($allowed)))),1);
253 return ($address.'@'.$domain);
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 {
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});
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)
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);
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));
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: exit code (0 for false, 1 for true, -1 for tempfail)
302 # $code : SMTP status code
303 # $message: SMTP status message
304 # \$log will be changed
306 my($smtpr,$recipient,$logr)=@_;
307 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
309 $$smtpr->to($recipient);
311 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
312 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
315 $$logr .= "---Connection failure---\n";
317 return ($success,$$smtpr->code,$$smtpr->message);
320 ################################ log_smtp_reply ################################
321 # log result of SMTP command
322 # IN : \$log : reference to the log (to be printed out via -l)
323 # $code : SMTP status code
324 # @message : SMTP status message
326 # \$log will be changed
328 my($logr,$code,@message)=@_;
329 $$logr .= sprintf('%s %s',$code,join('- ',@message));
333 ############################### analyze_smtp_reply ##############################
334 # analyze SMTP response codes and messages
335 # IN : $code : SMTP status code
336 # @message : SMTP status message
337 # OUT: exit code (0 for false, 1 for true, -1 for tempfail)
338 sub analyze_smtp_reply {
339 my($code,@message)=@_;
340 my $type = substr($code, 0, 1);
343 } elsif ($type == 5) {
345 } elsif ($type == 4) {
351 ############################## connection_failed ###############################
352 # print failure message and return status 1
353 # IN : @message : SMTP status message
355 sub connection_failed {
357 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
358 printf(" %s\n",join(' ',@message)) if @message;
364 ################################ Documentation #################################
368 checkmail - check deliverability of a mail address
372 B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] I<address>|B<-f> I<file>
392 Mail::Address I<(CPAN)>
404 Furthermore you'll need a working DNS installation.
408 checkmail checks the vailidity / deliverability of a mail address.
409 You may submit just one address as the last argument or a file
410 containing one address on each line using the B<-f> option.
414 For the time being, all configuration is done in the script. You have
415 to set the following elements of the %config hash:
419 =item B<$config{'helo'}>
421 The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
423 =item B<$config{'from'}>
425 The sender address to be used for I<MAIL FROM> while testing.
431 After configuring the script you may run your first test with
433 checkmail user@example.org
435 B<checkmail> will try to determine the mail exchanger(s) (MX)
436 responsible for I<example.org> by querying the DNS for the respective
437 MX records and then try to connect via SMTP (on port 25) to each of
438 them in order of precedence (if necessary). It will run through the
439 SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
440 I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
441 fall back to the I<example.org> host itself, provided there is at
442 least one A record defined in the DNS. If there are neither MX nor A
443 records for I<example.org>, mail is not deliverable and B<checkmail>
444 will fail accordingly. If no host can be reached, B<checkmail> will
445 fail, too. Finally B<checkmail> will fail if mail to the given
446 recipient is not accepted by the respective host.
448 If B<checkmail> fails, you'll not be able to deliver mail to that
449 address - at least not using the configured sender address and from
450 the host you're testing from. However, the opposite is not true: a
451 mail you send may still not be delivered even if a test via
452 B<checkmail> succeeds. The receiving entity may reject your mail after
453 the I<DATA> stage, due to content checking or without any special
454 reason, or it may even drop, filter or bounce your mail after finally
455 accepting it. There is no way to be sure a mail will be accepted short
456 of sending a real mail to the address in question.
458 You may, however, try to detect hosts that will happily accept any and
459 all recipient in the SMTP dialog and just reject your mail later on,
460 for example to defeat exactly the kind of check you try to do.
461 B<checkmail> will do that by submitting a recipient address that is
462 known to be invalid; if that address is accepted, too, you'll know
463 that you can't reliably check the validity of any address on that
464 host. You can force that check by using the B<-r> option.
466 If you don't want to see just the results of your test, you can get a
467 B<complete log> of the SMTP dialog by using the B<-l> option. That may be
468 helpful to test for temporary failure conditions.
470 On the other hand you may use the B<-q> option to suppress all output;
471 B<checkmail> will then terminate with one of the following B<exit
478 address(es) seem/seems to be valid
482 temporary error (connection failure or temporary failure)
490 address cannot reliably be checked (test using B<-r> failed)
494 You can do B<batch processing> using B<-f> and submitting a file with
495 one address on each line. In that case the exit status is set to the
496 highest value generated by testing all addresses, i.e. it is set to
497 B<0> if and only if no adress failed, but to B<2> if even one address
498 failed and to B<3> if even one addresses couldn't reliably be checked.
500 And finally you can B<suppress DNS lookups> for MX and A records and
501 just force B<checkmail> to connect to a particular host using the
504 B<Please note:> You shouldn't try to validate addresses while working
505 from a dial-up or blacklisted host. If in doubt, use the B<-l> option
506 to have a closer look on the SMTP dialog yourself.
512 =item B<-V> (version)
514 Print out version and copyright information on B<checkmail> and exit.
518 Print this man page and exit.
522 Suppress output and just terminate with a specific exit status.
526 Log and print out the whole SMTP dialog.
528 =item B<-r> (random address)
530 Also try a reliably invalid address to catch hosts that try undermine
531 address verification.
533 =item B<-m> I<host> (MX to use)
535 Force a connection to I<host> to check deliverability to that
536 particular host irrespective of DNS entries. For example:
538 checkmail -m test.host.example user@domain.example
540 =item B<-f> I<file> (file)
542 Process all addresses from I<file> (one on each line).
548 Just copy checkmail to some directory and get started.
550 You can run your first test with
552 checkmail user@example.org
556 See documentation of I<Net::DNS::Resolver>.
562 =item F<checkmail.pl>
570 Please report any bugs or feature request to the author or use the
571 bug tracker at L<http://bugs.th-h.de/>!
575 L<http://th-h.de/download/scripts.php> will have the current
576 version of this program.
578 This program is maintained using the Git version control system. You
579 may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
580 current development tree or browse it on the web via
581 L<http://code.th-h.de/?p=mail/checkmail.git>.
585 Thomas Hochstein <thh@inter.net>
587 =head1 COPYRIGHT AND LICENSE
589 Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
591 This program is free software; you may redistribute it and/or modify it
592 under the same terms as Perl itself.