Add documentation in POD format.
authorThomas Hochstein <thh@inter.net>
Wed, 16 Jun 2010 14:43:23 +0000 (16:43 +0200)
committerThomas Hochstein <thh@inter.net>
Wed, 16 Jun 2010 19:11:43 +0000 (21:11 +0200)
- Add POD.
- Drop checkmail.readme.

Signed-off-by: Thomas Hochstein <thh@inter.net>
checkmail.pl
checkmail.readme [deleted file]

index b7da4e2..e93a946 100644 (file)
@@ -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
diff --git a/checkmail.readme b/checkmail.readme
deleted file mode 100644 (file)
index 46c1fa0..0000000
+++ /dev/null
@@ -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.
This page took 0.014858 seconds and 4 git commands to generate.