Add documentation in POD format.

- Add POD.
- Drop checkmail.readme.

Signed-off-by: Thomas Hochstein <thh@inter.net>
This commit is contained in:
Thomas Hochstein 2010-06-16 16:43:23 +02:00
parent 431fbb1233
commit 32301d53af
2 changed files with 235 additions and 126 deletions

View file

@ -335,3 +335,238 @@ sub connection_failed {
print " > Connection failure.\n" if !($options{'q'}); print " > Connection failure.\n" if !($options{'q'});
return 1; return 1;
} }
__END__
################################ Documentation #################################
=head1 NAME
checkmail - check deliverability of a mail address
=head1 SYNOPSIS
B<checkmail> [B<-Vhqlr>] [B<-m> I<host>] I<address>|B<-f> I<file>
=head1 REQUIREMENTS
=over 2
=item -
Perl 5.8 or later
=item -
File::Basename
=item -
Getopt::Std
=item -
Net::DNS I<(CPAN)>
=item -
Net::SMTP
=back
Furthermore you'll need a working DNS installation.
=head1 DESCRIPTION
checkmail checks the vailidity / deliverability of a mail address.
You may submit just one address as the last argument or a file
containing one address on each line using the B<-f> option.
=head2 Configuration
For the time being, all configuration is done in the script. You have
to set the following elements of the %config hash:
=over 4
=item B<$config{'helo'}>
The hostname to be used for I<HELO> or I<EHLO> in the SMTP dialog.
=item B<$config{'from'}>
The sender address to be used for I<MAIL FROM> while testing.
=item B<$config{'rand'}>
A "random" local part to construct a reliably invalid address for use
with the B<-r> option.
=back
=head2 Usage
After configuring the script you may run your first test with
checkmail user@example.org
B<checkmail> will try to determine the mail exchanger(s) (MX)
responsible for I<example.org> by querying the DNS for the respective
MX records and then try to connect via SMTP (on port 25) to each of
them in order of precedence (if necessary). It will run through the
SMTP dialog until just before the I<DATA> stage, i.e. doing I<EHLO>,
I<MAIL FROM> and I<RCPT TO>. If no MX is defined, B<checkmail> will
fall back to the I<example.org> host itself, provided there is at
least one A record defined in the DNS. If there are neither MX nor A
records for I<example.org>, mail is not deliverable and B<checkmail>
will fail accordingly. If no host can be reached, B<checkmail> will
fail, too. Finally B<checkmail> will fail if mail to the given
recipient is not accepted by the respective host.
If B<checkmail> fails, you'll not be able to deliver mail to that
address - at least not using the configured sender address and from
the host you're testing from. However, the opposite is not true: a
mail you send may still not be delivered even if a test via
B<checkmail> succeeds. The receiving entity may reject your mail after
the I<DATA> stage, due to content checking or without any special
reason, or it may even drop, filter or bounce your mail after finally
accepting it. There is no way to be sure a mail will be accepted short
of sending a real mail to the address in question.
You may, however, try to detect hosts that will happily accept any and
all recipient in the SMTP dialog and just reject your mail later on,
for example to defeat exactly the kind of check you try to do.
B<checkmail> will do that by submitting a recipient address that is
known to be invalid; if that address is accepted, too, you'll know
that you can't reliably check the validity of any address on that
host. You can force that check by using the B<-r> option.
If you don't want to see just the results of your test, you can get a
B<complete log> of the SMTP dialog by using the B<-l> option. That may be
helpful to test for temporary failure conditions.
On the other hand you may use the B<-q> option to suppress all output;
B<checkmail> will then terminate with one of the following B<exit
status>:
=over 4
=item B<0>
address(es) seem/seems to be valid
=item B<1>
temporary error (connection failure or temporary failure)
=item B<2>
address is invalid
=item B<3>
address cannot reliably be checked (test using B<-r> failed)
=back
You can do B<batch processing> using B<-f> and submitting a file with
one address on each line. In that case the exit status is set to the
highest value generated by testing all addresses, i.e. it is set to
B<0> if and only if no adress failed, but to B<2> if even one address
failed and to B<3> if even one addresses couldn't reliably be checked.
And finally you can B<suppress DNS lookups> for MX and A records and
just force B<checkmail> to connect to a particular host using the
B<-m> option.
B<Please note:> You shouldn't try to validate addresses while working
from a dial-up or blacklisted host. If in doubt, use the B<-l> option
to have a closer look on the SMTP dialog yourself.
=head1 OPTIONS
=over 3
=item B<-V> (version)
Print out version and copyright information on B<checkmail> and exit.
=item B<-h> (help)
Print this man page and exit.
=item B<-q> (quit)
Suppress output and just terminate with a specific exit status.
=item B<-l> (log)
Log and print out the whole SMTP dialog.
=item B<-r> (random address)
Also try a reliably invalid address - defined in B<$config{'rand'}> -
to catch hosts that try undermine address verification.
=item B<-m> I<host> (MX to use)
Force a connection to I<host> to check deliverability to that
particular host irrespective of DNS entries. For example:
checkmail -m test.host.example user@domain.example
=item B<-f> I<file> (file)
Process all addresses from I<file> (one on each line).
=back
=head1 INSTALLATION
Just copy checkmail to some directory and get started.
You can run your first test with
checkmail user@example.org
=head1 ENVIRONMENT
See documentation of I<Net::DNS::Resolver>.
=head1 FILES
=over 4
=item F<checkmail.pl>
The script itself.
=back
=head1 BUGS
Please report any bugs or feature request to the author or use the
bug tracker at L<http://bugs.th-h.de/>!
=head1 SEE ALSO
L<http://th-h.de/download/scripts.php> will have the current
version of this program.
This program is maintained using the Git version control system. You
may clone L<git://code.th-h.de/mail/checkmail.git> to check out the
current development tree or browse it on the web via
L<http://code.th-h.de/?p=mail/checkmail.git>.
=head1 AUTHOR
Thomas Hochstein <thh@inter.net>
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2002-2010 Thomas Hochstein <thh@inter.net>
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
=cut

View file

@ -1,126 +0,0 @@
NAME
checkmail
SYNOPSIS
checkmail.pl [-hqlr] [-m <host>] -f <file>|<address>
DESCRIPTION
checkmail prüft die Zustellbarkeit von E-Mail-Adressen. Es ist
entweder die zu prüfende Adresse als letztes Argument oder
mit dem Parameter -f eine Datei mit zu prüfenden Adressen zu
übergeben.
Argumente:
-h
Mit dem Argument -h wird eine kurze Hilfe ausgegeben.
-q
Mit dem Argument -q werden alle Ausgaben unterdrückt;
das Script beendet sich nur mit einem Exit-Status zwischen
0 und 3.
-l
Mit dem Argument -l wird ein ausführliches Logging des
SMTP-Dialogs aktiviert.
-r
Mit dem Argument -r wird auch eine gezielt ungültige Adresse
geprüft, um festzustellen, ob der Host nicht einfach jede
Mailadresse ohne Prüfung akzeptiert.
-m
Mit dem Argument -m, gefolgt nach Leerzeichen von einem
Hostnamen, kann statt der Abfrage des für die Domain
zuständigen Hosts per DNS die Zustellfähigkeit bei einem
bestimmten Host geprüft werden.
Beispiel: checkmail.pl -m test.host.example mail@domain.example
-f
Mit dem Argument -f, gefolgt nach Leerzeichen von einem
Dateinamen, kann eine ganze Reihe von zu prüfenden Mailadressen
aus einer Datei eingelesen werden, die jeweils eine Adresse
pro Zeile enthält.
Beispiel: checkmail.pl -f adressen.txt
Basiskonfiguration:
Die Basiskonfiguration erfolgt innerhalb des Scripts. Anzugeben
sind:
$config{'helo'}:
Der im SMTP-Dialog für HELO/EHLO zu verwendende Hostname.
$config{'from'}:
Die Absenderadresse (Envelope-From:) für den Test.
$config{'rand'}:
Der Localpart der für den Parameter -r erforderlichen
zufälligen Adresse.
Funktionsweise:
Vor dem ersten Aufruf ist innerhalb des Scripts die
Basiskonfiguration vorzunehmen.
Danach kann das Script unter Angabe der zu prüfenden E-Mail-Adresse
aufgerufen werden. Es versucht den oder die zuständigen MX (Mail
eXchanger) für die Domain der Mailadresse zu ermitteln (ggf., falls
nicht vorhanden, an den entsprechenden Host zuzustellen), nach dort
zu verbinden und den SMTP-Dialog bis zum "RCPT TO:" durchzuführen,
um dann die Antwort des Mailservers auszuwerten.
Um Mailserver zu erkennen, die zunächst jede Mailadresse akzeptieren
und unerwünschte Mail erst später bouncen oder unterdrücken, kann
danach ein weiterer Test mit einer sicher ungültigen Mailadresse
ausgeführt werden (-r).
Nicht nur das Ergebnis des Tests, sondern auch der Dialog mit dem
Mailserver kann vermittels des Parameters -l ausgegeben werden; dies
ist hilfreich, um auszuschließen, daß die die Testverbindung aus
andere Gründen abgewiesen wird.
Wenn (gar) keine Textausgabe gewünscht ist, kann diese vermittels -q
unterdrückt werden; das Script beendet sich dann mit einem der vier
folgenden Statuscodes:
0: Adresse gültig oder Massenaufruf (-f)
1: Adresse ungültig
2: Adresse kann nicht geprüft werden (-r und negativer Test)
3: temporärer Fehler
Mehrere Mailadressen können mit Hilfe des Parameters -f innerhalb
einer Datei (eine Adresse pro Zeile) übergeben werden; in diesem
Fall wird immer der Status "0" zurückgegeben.
Schließlich kann mit Hilfe des Parameters -m die DNS-Abfrage
unterdrückt und die Verbindung zu einem bestimmten Host erzwungen
werden.
Hinweis: Der Test sollte nicht von einem Dialup-Host oder einem Host
auf einer sonstigen Blacklist aus durchgeführt werden! Ggf. kann ein
erneuter Aufruf von checkmail.pl -l für Klarheit sorgen, ob der Test
wegen der Auswertung einer Blacklist - unabhängig von der verwendeten
Adresse - fehlschlägt.
DEPENDANCIES
Die folgenden CPAN-Module werden neben Perl 5.6.1 oder höher benötigt:
Net::DNS
BUGS
- Fehler und Fehleingaben werden größtenteils nicht abgefangen.
Weitere Bugs nimmt <thh@inter.net> gerne entgegen.
AUTHOR
Thomas Hochstein <thh@inter.net>
VERSION
V 0.2 [beta]
COPYRIGHT
© 2002-2005 Thomas Hochstein.
See source for license und warranty.