From: Thomas Hochstein Date: Wed, 16 Jun 2010 14:43:23 +0000 (+0200) Subject: Add documentation in POD format. X-Git-Tag: v0.3~1 X-Git-Url: https://code.th-h.de/?p=mail%2Fcheckmail.git;a=commitdiff_plain;h=32301d53af29a1be028a61edc339275761d01f56 Add documentation in POD format. - Add POD. - Drop checkmail.readme. Signed-off-by: Thomas Hochstein --- diff --git a/checkmail.pl b/checkmail.pl index b7da4e2..e93a946 100644 --- a/checkmail.pl +++ b/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 [B<-Vhqlr>] [B<-m> I] I
|B<-f> I + +=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 or I in the SMTP dialog. + +=item B<$config{'from'}> + +The sender address to be used for I 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 will try to determine the mail exchanger(s) (MX) +responsible for I 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 stage, i.e. doing I, +I and I. If no MX is defined, B will +fall back to the I host itself, provided there is at +least one A record defined in the DNS. If there are neither MX nor A +records for I, mail is not deliverable and B +will fail accordingly. If no host can be reached, B will +fail, too. Finally B will fail if mail to the given +recipient is not accepted by the respective host. + +If B 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 succeeds. The receiving entity may reject your mail after +the I 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 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 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 will then terminate with one of the following B: + +=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 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 for MX and A records and +just force B to connect to a particular host using the +B<-m> option. + +B 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 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 (MX to use) + +Force a connection to I 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) + +Process all addresses from I (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. + +=head1 FILES + +=over 4 + +=item F + +The script itself. + +=back + +=head1 BUGS + +Please report any bugs or feature request to the author or use the +bug tracker at L! + +=head1 SEE ALSO + +L will have the current +version of this program. + +This program is maintained using the Git version control system. You +may clone L to check out the +current development tree or browse it on the web via +L. + +=head1 AUTHOR + +Thomas Hochstein + +=head1 COPYRIGHT AND LICENSE + +Copyright (c) 2002-2010 Thomas Hochstein + +This program is free software; you may redistribute it and/or modify it +under the same terms as Perl itself. + +=cut diff --git a/checkmail.readme b/checkmail.readme deleted file mode 100644 index 46c1fa0..0000000 --- a/checkmail.readme +++ /dev/null @@ -1,126 +0,0 @@ -NAME - checkmail - -SYNOPSIS - checkmail.pl [-hqlr] [-m ] -f |
- -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 gerne entgegen. - -AUTHOR - Thomas Hochstein - -VERSION - V 0.2 [beta] - -COPYRIGHT - © 2002-2005 Thomas Hochstein. - See source for license und warranty.