Add .gitattributes
[mail/checkmail.git] / checkmail.pl
CommitLineData
431fbb12 1#! /usr/bin/perl -W
0bd5c08c 2#
ea5d225a 3# checkmail Version 0.5 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
ea5d225a 12our $VERSION = "0.5";
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 = $_;
ea5d225a 95 # regexp taken from http://www.regular-expressions.info/email.html
5327436f
TH
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) {
ea5d225a 99 printf(" > Address <%s> is syntactically INVALID.\n",$address) if !($options{'q'});
431fbb12 100 $curstat = 2;
ea5d225a
TH
101 } else {
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)};
108 } else {
109 $message = sprintf("Connection to %s forced by -m.\n",$options{'m'});
110 $log .= $message;
111 print " $message" if !($options{'q'});
112 # just one target host with preference 0
113 $targets{$options{'m'}} = 0;
114 };
115 if (%targets) {
116 $curstat = checkaddress($address,\%targets,\$log);
117 } else {
118 $curstat = 2;
119 $message = 'DNS lookup failure';
120 printf(" > Address is INVALID (%s).\n",$message) if !($options{'q'});
121 $log .= $message . '.';
122 };
123 $log .= "====== END $address ======\n";
431fbb12 124 };
431fbb12 125 $status = $curstat if (!defined($status) or $curstat > $status);
0bd5c08c
TH
126};
127
128print $log if ($options{'l'});
129
130# status 0: valid / batch processing
431fbb12
TH
131# 1: connection failed or temporary failure
132# 2: invalid
133# 3: cannot verify
134#D print "\n-> EXIT $status\n";
0bd5c08c
TH
135exit($status);
136
431fbb12
TH
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
141sub gettargets {
142 my ($domain,$logr) = @_;
143 # resolver objekt
144 my $resolver = Net::DNS::Resolver->new(udp_timeout => 15, tcp_timeout => 15);
0bd5c08c 145
431fbb12
TH
146 my %targets;
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);
153 };
154 # no MX record found; log and try A record(s)
155 } else {
156 print_dns_result($domain,'MX',undef,$resolver->errorstring,$logr);
157 print(" Falling back to A record ...\n") if !($options{'q'});
158 # get A record(s)
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);
164 };
165 # no A record found either; log and fail
166 } else {
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'});
169 };
0bd5c08c 170 };
431fbb12
TH
171 return \%targets;
172};
173
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)
179# OUT: ---
180# \$log will be changed
181sub checkaddress {
182 my ($address,$targetsr,$logr) = @_;
183 my %targets = %{$targetsr};
184 my $status;
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);
0bd5c08c 191 };
431fbb12 192 return $status;
0bd5c08c
TH
193};
194
431fbb12
TH
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
0bd5c08c 203sub checksmtp {
431fbb12
TH
204 my ($address,$target,$logr) = @_;
205 my ($status);
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);
214 # test address
215 my ($success,$code,@message) = try_rcpt_to(\$smtp,$address,$logr);
216 # connection failure?
217 if ($success < 0) {
f18dc26f 218 $status = connection_failed(@message);
431fbb12
TH
219 # delivery attempt was successful?
220 } elsif ($success) {
221 # -r: try random address (which should be guaranteed to be invalid)
222 if ($options{'r'}) {
fd1fe450 223 my ($success,$code,@message) = try_rcpt_to(\$smtp,create_rand_addr(Mail::Address->new('',$address)->host),$logr);
431fbb12
TH
224 # connection failure?
225 if ($success < 0) {
f18dc26f 226 $status = connection_failed(@message);
431fbb12
TH
227 # verification impossible?
228 } elsif ($success) {
229 $status = 3;
230 print " > Address verificaton impossible. You'll have to send a test mail ...\n" if !($options{'q'});
231 }
232 }
233 # if -r is not set or status was not set to 3: valid address
234 if (!defined($status)) {
235 $status = 0;
236 print " > Address is valid.\n" if !($options{'q'});
0bd5c08c 237 };
431fbb12
TH
238 # delivery attempt failed?
239 } else {
240 $status = 2;
241 print " > Address is INVALID:\n" if !($options{'q'});
242 print ' ' . join(' ',@message) if !($options{'q'});
243 }
244 # terminate SMTP connection
245 $smtp->quit;
246 $$logr .= "QUIT\n";
247 log_smtp_reply($logr,$smtp->code,$smtp->message);
0bd5c08c 248 } else {
431fbb12
TH
249 # SMTP connection failed / timeout
250 $status = connection_failed();
251 $$logr .= "---Connection failure---\n";
0bd5c08c 252 };
431fbb12
TH
253 return $status;
254}
255
9fc0e927
TH
256############################### create_rand_addr ###############################
257# create a random mail address
258# IN : $domain: the domain part
259# OUT: $address: the address
260sub create_rand_addr {
261 my($domain)=@_;
262 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
263 my $address = '';
264 while (length($address) < 15) {
265 $address .= substr($allowed, (int(rand(length($allowed)))),1);
266 };
267 return ($address.'@'.$domain);
268};
269
431fbb12
TH
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)"
274sub parse_dns_reply {
275 my($response)=@_;
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});
284 } else {
285 return $response;
286 };
287};
288
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)
296# OUT: ---
297# \$log will be changed
298sub 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);
303 } else {
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));
306 };
307 return;
0bd5c08c
TH
308};
309
431fbb12
TH
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)
f18dc26f 315# OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
431fbb12
TH
316# $code : SMTP status code
317# $message: SMTP status message
318# \$log will be changed
319sub try_rcpt_to {
320 my($smtpr,$recipient,$logr)=@_;
321 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
f18dc26f
TH
322 my $success;
323 $$smtpr->to($recipient);
431fbb12
TH
324 if ($$smtpr->code) {
325 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
f18dc26f 326 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
431fbb12
TH
327 } else {
328 $success = -1;
329 $$logr .= "---Connection failure---\n";
330 };
331 return ($success,$$smtpr->code,$$smtpr->message);
332};
333
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
339# OUT: ---
340# \$log will be changed
341sub log_smtp_reply {
342 my($logr,$code,@message)=@_;
343 $$logr .= sprintf('%s %s',$code,join('- ',@message));
344 return;
0bd5c08c
TH
345}
346
f18dc26f
TH
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)
352sub analyze_smtp_reply {
353 my($code,@message)=@_;
354 my $type = substr($code, 0, 1);
355 if ($type == 2) {
356 return 1;
357 } elsif ($type == 5) {
358 return 0;
359 } elsif ($type == 4) {
360 return -1;
361 };
362 return -1;
363}
364
431fbb12
TH
365############################## connection_failed ###############################
366# print failure message and return status 1
f18dc26f 367# IN : @message : SMTP status message
431fbb12
TH
368# OUT: 1
369sub connection_failed {
f18dc26f
TH
370 my(@message)=@_;
371 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
372 printf(" %s\n",join(' ',@message)) if @message;
431fbb12
TH
373 return 1;
374}
32301d53
TH
375
376__END__
377
378################################ Documentation #################################
379
380=head1 NAME
381
382checkmail - check deliverability of a mail address
383
384=head1 SYNOPSIS
385
2121a934 386B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
32301d53
TH
387
388=head1 REQUIREMENTS
389
390=over 2
391
392=item -
393
394Perl 5.8 or later
395
396=item -
397
398File::Basename
399
400=item -
401
402Getopt::Std
403
404=item -
405
fd1fe450
TH
406Mail::Address I<(CPAN)>
407
408=item -
409
32301d53
TH
410Net::DNS I<(CPAN)>
411
412=item -
413
414Net::SMTP
415
416=back
417
418Furthermore you'll need a working DNS installation.
419
420=head1 DESCRIPTION
421
422checkmail checks the vailidity / deliverability of a mail address.
423You may submit just one address as the last argument or a file
424containing one address on each line using the B<-f> option.
425
426=head2 Configuration
427
428For the time being, all configuration is done in the script. You have
429to set the following elements of the %config hash:
430
431=over 4
432
433=item B<$config{'helo'}>
434
435The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
436
437=item B<$config{'from'}>
438
439The sender address to be used for I<MAIL FROM> while testing.
440
32301d53
TH
441=back
442
2121a934
TH
443You may override that configuration by using the B<-e> and B<-s>
444command line options.
445
32301d53
TH
446=head2 Usage
447
448After configuring the script you may run your first test with
449
450 checkmail user@example.org
451
ea5d225a
TH
452B<checkmail> will check the address for syntactic validity. If the
453address is valid, it will try to determine the mail exchanger(s) (MX)
32301d53
TH
454responsible for I<example.org> by querying the DNS for the respective
455MX records and then try to connect via SMTP (on port 25) to each of
456them in order of precedence (if necessary). It will run through the
457SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
458I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
459fall back to the I<example.org> host itself, provided there is at
460least one A record defined in the DNS. If there are neither MX nor A
461records for I<example.org>, mail is not deliverable and B<checkmail>
462will fail accordingly. If no host can be reached, B<checkmail> will
463fail, too. Finally B<checkmail> will fail if mail to the given
464recipient is not accepted by the respective host.
465
466If B<checkmail> fails, you'll not be able to deliver mail to that
467address - at least not using the configured sender address and from
468the host you're testing from. However, the opposite is not true: a
469mail you send may still not be delivered even if a test via
470B<checkmail> succeeds. The receiving entity may reject your mail after
471the I<DATA> stage, due to content checking or without any special
472reason, or it may even drop, filter or bounce your mail after finally
473accepting it. There is no way to be sure a mail will be accepted short
474of sending a real mail to the address in question.
475
476You may, however, try to detect hosts that will happily accept any and
477all recipient in the SMTP dialog and just reject your mail later on,
478for example to defeat exactly the kind of check you try to do.
479B<checkmail> will do that by submitting a recipient address that is
480known to be invalid; if that address is accepted, too, you'll know
481that you can't reliably check the validity of any address on that
482host. You can force that check by using the B<-r> option.
483
484If you don't want to see just the results of your test, you can get a
485B<complete log> of the SMTP dialog by using the B<-l> option. That may be
486helpful to test for temporary failure conditions.
487
488On the other hand you may use the B<-q> option to suppress all output;
489B<checkmail> will then terminate with one of the following B<exit
490status>:
491
492=over 4
493
494=item B<0>
495
496address(es) seem/seems to be valid
497
498=item B<1>
499
500temporary error (connection failure or temporary failure)
501
502=item B<2>
503
504address is invalid
505
506=item B<3>
507
508address cannot reliably be checked (test using B<-r> failed)
509
510=back
511
512You can do B<batch processing> using B<-f> and submitting a file with
513one address on each line. In that case the exit status is set to the
514highest value generated by testing all addresses, i.e. it is set to
515B<0> if and only if no adress failed, but to B<2> if even one address
516failed and to B<3> if even one addresses couldn't reliably be checked.
517
518And finally you can B<suppress DNS lookups> for MX and A records and
519just force B<checkmail> to connect to a particular host using the
520B<-m> option.
521
522B<Please note:> You shouldn't try to validate addresses while working
523from a dial-up or blacklisted host. If in doubt, use the B<-l> option
524to have a closer look on the SMTP dialog yourself.
525
9518c394
TH
526B<Please note:> To avoid shell expansion on addresses you submit to
527B<checkmail>, use B<batch processing>.
528
32301d53
TH
529=head1 OPTIONS
530
531=over 3
532
533=item B<-V> (version)
534
535Print out version and copyright information on B<checkmail> and exit.
536
537=item B<-h> (help)
538
539Print this man page and exit.
540
541=item B<-q> (quit)
542
543Suppress output and just terminate with a specific exit status.
544
545=item B<-l> (log)
546
547Log and print out the whole SMTP dialog.
548
549=item B<-r> (random address)
550
9fc0e927
TH
551Also try a reliably invalid address to catch hosts that try undermine
552address verification.
32301d53
TH
553
554=item B<-m> I<host> (MX to use)
555
556Force a connection to I<host> to check deliverability to that
557particular host irrespective of DNS entries. For example:
558
559 checkmail -m test.host.example user@domain.example
560
2121a934
TH
561=item B<-s> I<sender> (value for MAIL FROM)
562
563Override configuration and use I<sender> for MAIL FROM.
564
565=item B<-e> I<EHLO> (value for EHLO)
566
567Override configuration and use I<EHLO> for EHLO.
568
32301d53
TH
569=item B<-f> I<file> (file)
570
571Process all addresses from I<file> (one on each line).
572
573=back
574
575=head1 INSTALLATION
576
577Just copy checkmail to some directory and get started.
578
579You can run your first test with
580
581 checkmail user@example.org
582
583=head1 ENVIRONMENT
584
585See documentation of I<Net::DNS::Resolver>.
586
587=head1 FILES
588
589=over 4
590
591=item F<checkmail.pl>
592
593The script itself.
594
595=back
596
597=head1 BUGS
598
599Please report any bugs or feature request to the author or use the
600bug tracker at L<http://bugs.th-h.de/>!
601
602=head1 SEE ALSO
603
604L<http://th-h.de/download/scripts.php> will have the current
605version of this program.
606
607This program is maintained using the Git version control system. You
608may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
609current development tree or browse it on the web via
610L<http://code.th-h.de/?p=mail/checkmail.git>.
611
612=head1 AUTHOR
613
614Thomas Hochstein <thh@inter.net>
615
616=head1 COPYRIGHT AND LICENSE
617
618Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
619
620This program is free software; you may redistribute it and/or modify it
621under the same terms as Perl itself.
622
623=cut
This page took 0.043281 seconds and 4 git commands to generate.