Add changelog.
[mail/checkmail.git] / checkmail.pl
CommitLineData
431fbb12 1#! /usr/bin/perl -W
0bd5c08c 2#
431fbb12
TH
3# checkmail Version 0.3 by Thomas Hochstein
4#
5# This script tries to verify the deliverability of (a) mail address(es).
6#
7# Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
0bd5c08c 8#
431fbb12
TH
9# It can be redistributed and/or modified under the same terms under
10# which Perl itself is published.
11
12our $VERSION = "0.3";
13
14################################# Configuration ################################
15# Please fill in a working configuration!
16my %config=(
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',
21 # a syntactically valid "random" - reliably not existing - localpart
22 rand => 'ZOq62fow1i'
23 );
24
25################################### Modules ####################################
26use strict;
27use File::Basename;
0bd5c08c
TH
28use Getopt::Std;
29use Net::DNS;
30use Net::SMTP;
31
431fbb12
TH
32################################# Main program #################################
33
34$Getopt::Std::STANDARD_HELP_VERSION = 1;
35my $myself = basename($0);
36
37# read commandline options
0bd5c08c 38my %options;
431fbb12
TH
39getopts('Vhqlrf:m:', \%options);
40
41# -V: display version
42if ($options{'V'}) {
43 print "$myself v $VERSION\nCopyright (c) 2010 Thomas Hochstein <thh\@inter.net>\n";
44 print "This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.\n";
45 exit(100);
46};
47
48# -h: feed myself to perldoc
49if ($options{'h'}) {
50 exec('perldoc', $0);
51 exit(100);
52};
53
54# display usage information if neither -f nor an address are present
55if (!$options{'f'} and !$ARGV[0]) {
56 print "Usage: $myself [-hqlr] [-m <host>] <address>|-f <file>\n";
57 print "Options: -V display copyright and version\n";
58 print " -h show documentation\n";
59 print " -q quiet (no output, just exit with 0/1/2/3)\n";
60 print " -l extended logging\n";
61 print " -r test random address to verify verification\n";
62 print " -m <host> no DNS lookup, just test this host\n";
63 print " <address> mail address to check\n\n";
64 print " -f <file> parse file (one address per line)\n";
65 exit(100);
0bd5c08c
TH
66};
67
431fbb12
TH
68# -f: open file and read addresses to @adresses
69my @addresses;
0bd5c08c
TH
70if ($options{'f'}) {
71 if (-e $options{'f'}) {
431fbb12 72 open FILE, "<$options{'f'}" or die("$myself ERROR: Could not open file $options{'f'} for reading: $!");
0bd5c08c 73 } else {
431fbb12 74 die("$myself ERROR: File $options{'f'} does not exist!\n");
0bd5c08c 75 };
0bd5c08c
TH
76 while(<FILE>) {
77 chomp;
431fbb12 78 push(@addresses,$_);
0bd5c08c
TH
79 };
80 close FILE;
431fbb12
TH
81# fill @adresses with single address to check
82 } else {
83 push(@addresses,$ARGV[0]);
84};
85
86# loop over each address and test it
87my (%targets,$curstat,$status,$log,$message);
88foreach (@addresses) {
89 my $address = $_;
90 (undef,my $domain) = splitaddress($address);
91 printf(" * Testing %s ...\n",$address) if !($options{'q'});
92 $log .= "\n===== BEGIN $address =====\n";
93 # get list of target hosts or take host forced via -m
94 if (!$options{'m'}) {
95 %targets = %{gettargets($domain,\$log)};
96 } else {
97 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
98 $log .= $message;
99 print " $message" if !($options{'q'});
100 # just one target host with preference 0
101 $targets{$options{'m'}} = 0;
102 };
103 if (%targets) {
104 $curstat = checkaddress($address,\%targets,\$log);
105 } else {
106 $curstat = 2;
107 $message = 'DNS lookup failure';
108 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
109 $log .= $message . '.';
110 };
111 $log .= "====== END $address ======\n";
112 $status = $curstat if (!defined($status) or $curstat > $status);
0bd5c08c
TH
113};
114
115print $log if ($options{'l'});
116
117# status 0: valid / batch processing
431fbb12
TH
118# 1: connection failed or temporary failure
119# 2: invalid
120# 3: cannot verify
121#D print "\n-> EXIT $status\n";
0bd5c08c
TH
122exit($status);
123
431fbb12
TH
124################################## gettargets ##################################
125# get mail exchanger(s) or A record(s) for a domain
126# IN : $domain: domain to query the DNS for
127# OUT: \%targets: reference to a hash containing a list of target hosts
128sub gettargets {
129 my ($domain,$logr) = @_;
130 # resolver objekt
131 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
0bd5c08c 132
431fbb12
TH
133 my %targets;
134 # get MX record(s) as a list sorted by preference
135 if (my @mxrr = mx($resolver,$domain)) {
136 print_dns_result($domain,'MX',scalar(@mxrr),undef,$logr);
137 foreach my $rr (@mxrr) {
138 $targets{$rr->exchange} = $rr->preference;
139 $$logr .= sprintf("(%d) %s\n",$rr->preference,$rr->exchange);
140 };
141 # no MX record found; log and try A record(s)
142 } else {
143 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
144 print(" Falling back to A record ...\n") if !($options{'q'});
145 # get A record(s)
146 if (my $query = $resolver->query($domain,'A','IN')) {
147 print_dns_result($domain,'A',$query->header->ancount,undef,$logr);
148 foreach my $rr ($query->answer) {
149 $targets{$rr->address} = 0;
150 $$logr .= sprintf("- %s\n",$rr->address);
151 };
152 # no A record found either; log and fail
153 } else {
154 print_dns_result($domain,'A',undef,$resolver->errorstring,$logr);
155 printf(" %s has neither MX nor A records - mail cannot be delivered.\n",$domain) if !($options{'q'});
156 };
0bd5c08c 157 };
431fbb12
TH
158 return \%targets;
159};
160
161################################# checkaddress #################################
162# test address for deliverability
163# IN : $address: adress to be tested
164# \%targets: reference to a hash containing a list of MX hosts
165# \$log : reference to the log (to be printed out via -l)
166# OUT: ---
167# \$log will be changed
168sub checkaddress {
169 my ($address,$targetsr,$logr) = @_;
170 my %targets = %{$targetsr};
171 my $status;
172 # walk %targets in order of preference
173 foreach my $host (sort { $targets{$a} <=> $targets{$b} } keys %targets) {
174 printf(" / Trying %s (%s) with %s\n",$host,$targets{$host} || 'A',$address) if !($options{'q'});
175 $$logr .= sprintf("%s:\n%s\n",$host,"-" x (length($host)+1));
176 $status = checksmtp($address,$host,$logr);
177 last if ($status != 1);
0bd5c08c 178 };
431fbb12 179 return $status;
0bd5c08c
TH
180};
181
431fbb12
TH
182################################### checksmtp ##################################
183# connect to a remote machine on port 25 and test deliverability of a mail
184# address by doing the SMTP dialog until RCPT TO stage
185# IN : $address: address to test
186# $target : target host
187# \$log : reference to the log (to be printed out via -l)
188# OUT: .........: reference to a hash containing a list of target hosts
189# \$log will be changed
0bd5c08c 190sub checksmtp {
431fbb12
TH
191 my ($address,$target,$logr) = @_;
192 my ($status);
193 # start SMTP connection
194 if (my $smtp = Net::SMTP->new($target,Hello => $config{'helo'},Timeout => 30)) {
195 $$logr .= $smtp->banner; # Net::SMTP doesn't seem to support multiline greetings.
196 $$logr .= "EHLO $config{'helo'}\n";
197 log_smtp_reply($logr,$smtp->code,$smtp->message);
198 $smtp->mail($config{'from'});
199 $$logr .= "MAIL FROM:<$config{'from'}>\n";
200 log_smtp_reply($logr,$smtp->code,$smtp->message);
201 # test address
202 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
203 # connection failure?
204 if ($success < 0) {
205 $status = connection_failed();
206 # delivery attempt was successful?
207 } elsif ($success) {
208 # -r: try random address (which should be guaranteed to be invalid)
209 if ($options{'r'}) {
210 (undef,my $domain) = splitaddress($address);
211 my ($success,$code,@message) = try_rcpt_to(\$smtp,$config{'rand'}.'@'.$domain,$logr);
212 # connection failure?
213 if ($success < 0) {
214 $status = connection_failed();
215 # verification impossible?
216 } elsif ($success) {
217 $status = 3;
218 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
219 }
220 }
221 # if -r is not set or status was not set to 3: valid address
222 if (!defined($status)) {
223 $status = 0;
224 print " > Address is valid.\n" if !($options{'q'});
0bd5c08c 225 };
431fbb12
TH
226 # delivery attempt failed?
227 } else {
228 $status = 2;
229 print " > Address is INVALID:\n" if !($options{'q'});
230 print ' ' . join(' ',@message) if !($options{'q'});
231 }
232 # terminate SMTP connection
233 $smtp->quit;
234 $$logr .= "QUIT\n";
235 log_smtp_reply($logr,$smtp->code,$smtp->message);
0bd5c08c 236 } else {
431fbb12
TH
237 # SMTP connection failed / timeout
238 $status = connection_failed();
239 $$logr .= "---Connection failure---\n";
0bd5c08c 240 };
431fbb12
TH
241 return $status;
242}
243
244################################# splitaddress #################################
245# split mail address into local and domain part
246# IN : $address: a mail address
247# OUT: $local : local part
248# $domain: domain part
249sub splitaddress {
250 my($address)=@_;
251 (my $lp = $address) =~ s/^([^@]+)@.*/$1/;
252 (my $domain = $address) =~ s/[^@]+\@(\S*)$/$1/;
253 return ($lp,$domain);
254};
255
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)"
260sub parse_dns_reply {
261 my($response)=@_;
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});
270 } else {
271 return $response;
272 };
273};
274
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)
282# OUT: ---
283# \$log will be changed
284sub 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);
289 } else {
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));
292 };
293 return;
0bd5c08c
TH
294};
295
431fbb12
TH
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: true or false
302# $code : SMTP status code
303# $message: SMTP status message
304# \$log will be changed
305sub try_rcpt_to {
306 my($smtpr,$recipient,$logr)=@_;
307 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
308 my $success = $$smtpr->to($recipient);
309 if ($$smtpr->code) {
310 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
311 } else {
312 $success = -1;
313 $$logr .= "---Connection failure---\n";
314 };
315 return ($success,$$smtpr->code,$$smtpr->message);
316};
317
318################################ log_smtp_reply ################################
319# log result of SMTP command
320# IN : \$log : reference to the log (to be printed out via -l)
321# $code : SMTP status code
322# @message : SMTP status message
323# OUT: ---
324# \$log will be changed
325sub log_smtp_reply {
326 my($logr,$code,@message)=@_;
327 $$logr .= sprintf('%s %s',$code,join('- ',@message));
328 return;
0bd5c08c
TH
329}
330
431fbb12
TH
331############################## connection_failed ###############################
332# print failure message and return status 1
333# OUT: 1
334sub connection_failed {
335 print " > Connection failure.\n" if !($options{'q'});
336 return 1;
337}
32301d53
TH
338
339__END__
340
341################################ Documentation #################################
342
343=head1 NAME
344
345checkmail - check deliverability of a mail address
346
347=head1 SYNOPSIS
348
349B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] I<address>|B<-f> I<file>
350
351=head1 REQUIREMENTS
352
353=over 2
354
355=item -
356
357Perl 5.8 or later
358
359=item -
360
361File::Basename
362
363=item -
364
365Getopt::Std
366
367=item -
368
369Net::DNS I<(CPAN)>
370
371=item -
372
373Net::SMTP
374
375=back
376
377Furthermore you'll need a working DNS installation.
378
379=head1 DESCRIPTION
380
381checkmail checks the vailidity / deliverability of a mail address.
382You may submit just one address as the last argument or a file
383containing one address on each line using the B<-f> option.
384
385=head2 Configuration
386
387For the time being, all configuration is done in the script. You have
388to set the following elements of the %config hash:
389
390=over 4
391
392=item B<$config{'helo'}>
393
394The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
395
396=item B<$config{'from'}>
397
398The sender address to be used for I<MAIL FROM> while testing.
399
400=item B<$config{'rand'}>
401
402A "random" local part to construct a reliably invalid address for use
403with the B<-r> option.
404
405=back
406
407=head2 Usage
408
409After configuring the script you may run your first test with
410
411 checkmail user@example.org
412
413B<checkmail> will try to determine the mail exchanger(s) (MX)
414responsible for I<example.org> by querying the DNS for the respective
415MX records and then try to connect via SMTP (on port 25) to each of
416them in order of precedence (if necessary). It will run through the
417SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
418I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
419fall back to the I<example.org> host itself, provided there is at
420least one A record defined in the DNS. If there are neither MX nor A
421records for I<example.org>, mail is not deliverable and B<checkmail>
422will fail accordingly. If no host can be reached, B<checkmail> will
423fail, too. Finally B<checkmail> will fail if mail to the given
424recipient is not accepted by the respective host.
425
426If B<checkmail> fails, you'll not be able to deliver mail to that
427address - at least not using the configured sender address and from
428the host you're testing from. However, the opposite is not true: a
429mail you send may still not be delivered even if a test via
430B<checkmail> succeeds. The receiving entity may reject your mail after
431the I<DATA> stage, due to content checking or without any special
432reason, or it may even drop, filter or bounce your mail after finally
433accepting it. There is no way to be sure a mail will be accepted short
434of sending a real mail to the address in question.
435
436You may, however, try to detect hosts that will happily accept any and
437all recipient in the SMTP dialog and just reject your mail later on,
438for example to defeat exactly the kind of check you try to do.
439B<checkmail> will do that by submitting a recipient address that is
440known to be invalid; if that address is accepted, too, you'll know
441that you can't reliably check the validity of any address on that
442host. You can force that check by using the B<-r> option.
443
444If you don't want to see just the results of your test, you can get a
445B<complete log> of the SMTP dialog by using the B<-l> option. That may be
446helpful to test for temporary failure conditions.
447
448On the other hand you may use the B<-q> option to suppress all output;
449B<checkmail> will then terminate with one of the following B<exit
450status>:
451
452=over 4
453
454=item B<0>
455
456address(es) seem/seems to be valid
457
458=item B<1>
459
460temporary error (connection failure or temporary failure)
461
462=item B<2>
463
464address is invalid
465
466=item B<3>
467
468address cannot reliably be checked (test using B<-r> failed)
469
470=back
471
472You can do B<batch processing> using B<-f> and submitting a file with
473one address on each line. In that case the exit status is set to the
474highest value generated by testing all addresses, i.e. it is set to
475B<0> if and only if no adress failed, but to B<2> if even one address
476failed and to B<3> if even one addresses couldn't reliably be checked.
477
478And finally you can B<suppress DNS lookups> for MX and A records and
479just force B<checkmail> to connect to a particular host using the
480B<-m> option.
481
482B<Please note:> You shouldn't try to validate addresses while working
483from a dial-up or blacklisted host. If in doubt, use the B<-l> option
484to have a closer look on the SMTP dialog yourself.
485
486=head1 OPTIONS
487
488=over 3
489
490=item B<-V> (version)
491
492Print out version and copyright information on B<checkmail> and exit.
493
494=item B<-h> (help)
495
496Print this man page and exit.
497
498=item B<-q> (quit)
499
500Suppress output and just terminate with a specific exit status.
501
502=item B<-l> (log)
503
504Log and print out the whole SMTP dialog.
505
506=item B<-r> (random address)
507
508Also try a reliably invalid address - defined in B<$config{'rand'}> -
509to catch hosts that try undermine address verification.
510
511=item B<-m> I<host> (MX to use)
512
513Force a connection to I<host> to check deliverability to that
514particular host irrespective of DNS entries. For example:
515
516 checkmail -m test.host.example user@domain.example
517
518=item B<-f> I<file> (file)
519
520Process all addresses from I<file> (one on each line).
521
522=back
523
524=head1 INSTALLATION
525
526Just copy checkmail to some directory and get started.
527
528You can run your first test with
529
530 checkmail user@example.org
531
532=head1 ENVIRONMENT
533
534See documentation of I<Net::DNS::Resolver>.
535
536=head1 FILES
537
538=over 4
539
540=item F<checkmail.pl>
541
542The script itself.
543
544=back
545
546=head1 BUGS
547
548Please report any bugs or feature request to the author or use the
549bug tracker at L<http://bugs.th-h.de/>!
550
551=head1 SEE ALSO
552
553L<http://th-h.de/download/scripts.php> will have the current
554version of this program.
555
556This program is maintained using the Git version control system. You
557may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
558current development tree or browse it on the web via
559L<http://code.th-h.de/?p=mail/checkmail.git>.
560
561=head1 AUTHOR
562
563Thomas Hochstein <thh@inter.net>
564
565=head1 COPYRIGHT AND LICENSE
566
567Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
568
569This program is free software; you may redistribute it and/or modify it
570under the same terms as Perl itself.
571
572=cut
This page took 0.03835 seconds and 4 git commands to generate.