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