Allow setting an empty envelope-from using '-s'.
[mail/checkmail.git] / checkmail.pl
CommitLineData
ba787c2d 1#! /usr/bin/perl -w
0bd5c08c 2#
ba787c2d 3# checkmail Version 0.6.1 by Thomas Hochstein
431fbb12
TH
4#
5# This script tries to verify the deliverability of (a) mail address(es).
6#
422d9071 7# Copyright (c) 2002-2011 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
240c1264 12our $VERSION = "0.6.2";
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'}) {
240c1264 42 print "$myself v $VERSION\nCopyright (c) 2010-2016 Thomas Hochstein <thh\@inter.net>\n";
431fbb12
TH
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 69# -s / -e: override configuration
240c1264 70$config{'from'} = $options{'s'} if defined($options{'s'});
2121a934
TH
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);
e8c5b7b2
TH
227 # reset status - the address has been checked and _is_ valid!
228 $status = 3;
229 print " > Address verification currently impossible. You'll have to try again or send a test mail ...\n" if !($options{'q'});
431fbb12
TH
230 # verification impossible?
231 } elsif ($success) {
232 $status = 3;
382c5a59 233 print " > Address verification impossible. You'll have to send a test mail ...\n" if !($options{'q'});
431fbb12
TH
234 }
235 }
236 # if -r is not set or status was not set to 3: valid address
237 if (!defined($status)) {
238 $status = 0;
239 print " > Address is valid.\n" if !($options{'q'});
0bd5c08c 240 };
431fbb12
TH
241 # delivery attempt failed?
242 } else {
243 $status = 2;
244 print " > Address is INVALID:\n" if !($options{'q'});
245 print ' ' . join(' ',@message) if !($options{'q'});
246 }
247 # terminate SMTP connection
248 $smtp->quit;
249 $$logr .= "QUIT\n";
250 log_smtp_reply($logr,$smtp->code,$smtp->message);
0bd5c08c 251 } else {
431fbb12
TH
252 # SMTP connection failed / timeout
253 $status = connection_failed();
254 $$logr .= "---Connection failure---\n";
0bd5c08c 255 };
431fbb12
TH
256 return $status;
257}
258
9fc0e927
TH
259############################### create_rand_addr ###############################
260# create a random mail address
261# IN : $domain: the domain part
262# OUT: $address: the address
263sub create_rand_addr {
264 my($domain)=@_;
265 my $allowed = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789-+_=';
266 my $address = '';
267 while (length($address) < 15) {
268 $address .= substr($allowed, (int(rand(length($allowed)))),1);
269 };
270 return ($address.'@'.$domain);
271};
272
431fbb12
TH
273################################ parse_dns_reply ###############################
274# parse DNS response codes and return code and description
275# IN : $response: a DNS response code
276# OUT: "$response ($desciption)"
277sub parse_dns_reply {
278 my($response)=@_;
279 my %dnsrespcodes = (NOERROR => 'empty response',
280 NXDOMAIN => 'non-existent domain',
281 SERVFAIL => 'DNS server failure',
282 REFUSED => 'DNS query refused',
283 FORMERR => 'format error',
284 NOTIMP => 'not implemented');
285 if(defined($dnsrespcodes{$response})) {
286 return sprintf('%s (%s)',$response,$dnsrespcodes{$response});
287 } else {
288 return $response;
289 };
290};
291
292############################### print_dns_result ###############################
293# print and log result of DNS query
294# IN : $domain: domain the DNS was queried for
295# $type : record type (MX, A, ...)
296# $count : number of records found
297# $error : DNS response code
298# \$log : reference to the log (to be printed out via -l)
299# OUT: ---
300# \$log will be changed
301sub print_dns_result {
302 my ($domain,$type,$count,$error,$logr) = @_;
303 if (defined($count)) {
304 printf(" %d %s record(s) found for %s\n",$count,$type,$domain) if !($options{'q'});
305 $$logr .= sprintf("%s DNS record(s):\n",$type);
306 } else {
307 printf(" No %s records found for %s: %s\n",$type,$domain,parse_dns_reply($error)) if !($options{'q'});
308 $$logr .= sprintf("No %s records found: %s\n",$type,parse_dns_reply($error));
309 };
310 return;
0bd5c08c
TH
311};
312
431fbb12
TH
313################################## try_rcpt_to #################################
314# send RCPT TO and return replies
315# IN : \$smtp : a reference to an SMTP object
316# $recipient: a mail address
317# \$log : reference to the log (to be printed out via -l)
f18dc26f 318# OUT: $success: exit code (0 for false, 1 for true, -1 for tempfail)
431fbb12
TH
319# $code : SMTP status code
320# $message: SMTP status message
321# \$log will be changed
322sub try_rcpt_to {
323 my($smtpr,$recipient,$logr)=@_;
324 $$logr .= sprintf("RCPT TO:<%s>\n",$recipient);
f18dc26f
TH
325 my $success;
326 $$smtpr->to($recipient);
431fbb12
TH
327 if ($$smtpr->code) {
328 log_smtp_reply($logr,$$smtpr->code,$$smtpr->message);
f18dc26f 329 $success = analyze_smtp_reply($$smtpr->code,$$smtpr->message);
431fbb12
TH
330 } else {
331 $success = -1;
332 $$logr .= "---Connection failure---\n";
333 };
334 return ($success,$$smtpr->code,$$smtpr->message);
335};
336
337################################ log_smtp_reply ################################
338# log result of SMTP command
339# IN : \$log : reference to the log (to be printed out via -l)
340# $code : SMTP status code
341# @message : SMTP status message
342# OUT: ---
343# \$log will be changed
344sub log_smtp_reply {
345 my($logr,$code,@message)=@_;
346 $$logr .= sprintf('%s %s',$code,join('- ',@message));
347 return;
0bd5c08c
TH
348}
349
f18dc26f
TH
350############################### analyze_smtp_reply ##############################
351# analyze SMTP response codes and messages
352# IN : $code : SMTP status code
353# @message : SMTP status message
354# OUT: exit code (0 for false, 1 for true, -1 for tempfail)
355sub analyze_smtp_reply {
356 my($code,@message)=@_;
357 my $type = substr($code, 0, 1);
358 if ($type == 2) {
359 return 1;
360 } elsif ($type == 5) {
361 return 0;
362 } elsif ($type == 4) {
363 return -1;
364 };
365 return -1;
366}
367
431fbb12
TH
368############################## connection_failed ###############################
369# print failure message and return status 1
f18dc26f 370# IN : @message : SMTP status message
431fbb12
TH
371# OUT: 1
372sub connection_failed {
f18dc26f
TH
373 my(@message)=@_;
374 print " ! Connection failed or other temporary failure.\n" if !($options{'q'});
375 printf(" %s\n",join(' ',@message)) if @message;
431fbb12
TH
376 return 1;
377}
32301d53
TH
378
379__END__
380
381################################ Documentation #################################
382
383=head1 NAME
384
385checkmail - check deliverability of a mail address
386
387=head1 SYNOPSIS
388
2121a934 389B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] [-s I<sender>] [-e I<EHLO>] I<address>|B<-f> I<file>
32301d53
TH
390
391=head1 REQUIREMENTS
392
393=over 2
394
395=item -
396
397Perl 5.8 or later
398
399=item -
400
401File::Basename
402
403=item -
404
405Getopt::Std
406
407=item -
408
fd1fe450
TH
409Mail::Address I<(CPAN)>
410
411=item -
412
32301d53
TH
413Net::DNS I<(CPAN)>
414
415=item -
416
417Net::SMTP
418
419=back
420
421Furthermore you'll need a working DNS installation.
422
423=head1 DESCRIPTION
424
425checkmail checks the vailidity / deliverability of a mail address.
426You may submit just one address as the last argument or a file
427containing one address on each line using the B<-f> option.
428
429=head2 Configuration
430
431For the time being, all configuration is done in the script. You have
432to set the following elements of the %config hash:
433
434=over 4
435
436=item B<$config{'helo'}>
437
438The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
439
440=item B<$config{'from'}>
441
442The sender address to be used for I<MAIL FROM> while testing.
240c1264 443May be empty ('') to set '<>' as MAIL FROM.
32301d53 444
32301d53
TH
445=back
446
2121a934
TH
447You may override that configuration by using the B<-e> and B<-s>
448command line options.
449
32301d53
TH
450=head2 Usage
451
452After configuring the script you may run your first test with
453
454 checkmail user@example.org
455
ea5d225a
TH
456B<checkmail> will check the address for syntactic validity. If the
457address is valid, it will try to determine the mail exchanger(s) (MX)
32301d53
TH
458responsible for I<example.org> by querying the DNS for the respective
459MX records and then try to connect via SMTP (on port 25) to each of
460them in order of precedence (if necessary). It will run through the
461SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
462I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
463fall back to the I<example.org> host itself, provided there is at
464least one A record defined in the DNS. If there are neither MX nor A
465records for I<example.org>, mail is not deliverable and B<checkmail>
466will fail accordingly. If no host can be reached, B<checkmail> will
467fail, too. Finally B<checkmail> will fail if mail to the given
468recipient is not accepted by the respective host.
469
470If B<checkmail> fails, you'll not be able to deliver mail to that
471address - at least not using the configured sender address and from
472the host you're testing from. However, the opposite is not true: a
473mail you send may still not be delivered even if a test via
474B<checkmail> succeeds. The receiving entity may reject your mail after
475the I<DATA> stage, due to content checking or without any special
476reason, or it may even drop, filter or bounce your mail after finally
477accepting it. There is no way to be sure a mail will be accepted short
478of sending a real mail to the address in question.
479
480You may, however, try to detect hosts that will happily accept any and
481all recipient in the SMTP dialog and just reject your mail later on,
482for example to defeat exactly the kind of check you try to do.
483B<checkmail> will do that by submitting a recipient address that is
484known to be invalid; if that address is accepted, too, you'll know
485that you can't reliably check the validity of any address on that
486host. You can force that check by using the B<-r> option.
487
488If you don't want to see just the results of your test, you can get a
489B<complete log> of the SMTP dialog by using the B<-l> option. That may be
490helpful to test for temporary failure conditions.
491
492On the other hand you may use the B<-q> option to suppress all output;
493B<checkmail> will then terminate with one of the following B<exit
494status>:
495
496=over 4
497
498=item B<0>
499
500address(es) seem/seems to be valid
501
502=item B<1>
503
504temporary error (connection failure or temporary failure)
505
506=item B<2>
507
508address is invalid
509
510=item B<3>
511
512address cannot reliably be checked (test using B<-r> failed)
513
514=back
515
516You can do B<batch processing> using B<-f> and submitting a file with
517one address on each line. In that case the exit status is set to the
518highest value generated by testing all addresses, i.e. it is set to
519B<0> if and only if no adress failed, but to B<2> if even one address
520failed and to B<3> if even one addresses couldn't reliably be checked.
521
522And finally you can B<suppress DNS lookups> for MX and A records and
523just force B<checkmail> to connect to a particular host using the
524B<-m> option.
525
526B<Please note:> You shouldn't try to validate addresses while working
527from a dial-up or blacklisted host. If in doubt, use the B<-l> option
528to have a closer look on the SMTP dialog yourself.
529
9518c394
TH
530B<Please note:> To avoid shell expansion on addresses you submit to
531B<checkmail>, use B<batch processing>.
532
32301d53
TH
533=head1 OPTIONS
534
535=over 3
536
537=item B<-V> (version)
538
539Print out version and copyright information on B<checkmail> and exit.
540
541=item B<-h> (help)
542
543Print this man page and exit.
544
545=item B<-q> (quit)
546
547Suppress output and just terminate with a specific exit status.
548
549=item B<-l> (log)
550
551Log and print out the whole SMTP dialog.
552
553=item B<-r> (random address)
554
9fc0e927
TH
555Also try a reliably invalid address to catch hosts that try undermine
556address verification.
32301d53
TH
557
558=item B<-m> I<host> (MX to use)
559
560Force a connection to I<host> to check deliverability to that
561particular host irrespective of DNS entries. For example:
562
563 checkmail -m test.host.example user@domain.example
564
2121a934
TH
565=item B<-s> I<sender> (value for MAIL FROM)
566
567Override configuration and use I<sender> for MAIL FROM.
568
569=item B<-e> I<EHLO> (value for EHLO)
570
571Override configuration and use I<EHLO> for EHLO.
572
32301d53
TH
573=item B<-f> I<file> (file)
574
575Process all addresses from I<file> (one on each line).
576
577=back
578
579=head1 INSTALLATION
580
581Just copy checkmail to some directory and get started.
582
583You can run your first test with
584
585 checkmail user@example.org
586
587=head1 ENVIRONMENT
588
589See documentation of I<Net::DNS::Resolver>.
590
591=head1 FILES
592
593=over 4
594
595=item F<checkmail.pl>
596
597The script itself.
598
599=back
600
601=head1 BUGS
602
603Please report any bugs or feature request to the author or use the
604bug tracker at L<http://bugs.th-h.de/>!
605
606=head1 SEE ALSO
607
608L<http://th-h.de/download/scripts.php> will have the current
609version of this program.
610
611This program is maintained using the Git version control system. You
612may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
613current development tree or browse it on the web via
614L<http://code.th-h.de/?p=mail/checkmail.git>.
615
616=head1 AUTHOR
617
618Thomas Hochstein <thh@inter.net>
619
620=head1 COPYRIGHT AND LICENSE
621
622Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
623
624This program is free software; you may redistribute it and/or modify it
625under the same terms as Perl itself.
626
627=cut
This page took 0.047481 seconds and 4 git commands to generate.