Add documentation in POD format.
- Add POD. - Drop checkmail.readme. Signed-off-by: Thomas Hochstein <thh@inter.net>
This commit is contained in:
parent
431fbb1233
commit
32301d53af
2 changed files with 235 additions and 126 deletions
235
checkmail.pl
235
checkmail.pl
|
|
@ -335,3 +335,238 @@ sub connection_failed {
|
|||
print " > Connection failure.\n" if !($options{'q'});
|
||||
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
|
||||
|
|
|
|||
126
checkmail.readme
126
checkmail.readme
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue