Added description of how mail processor command-lines work.

Added description of how mail processing error file works.
Added description of new recipient list file format.
Added support for mail processing command-line specifers: %h, %i, and %u.

ctrl/mailproc.cfg

 ; External Mail Processing Configuration
+; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ;
-; command-line specifiers (variables) available in command-lines:
+; $Id$
 ;
-;     %m mail message (header and body text) path/filename
-;     %l recipient list path/filename
-;     %e processing error path/filename (put error text in this file)
+; Overview
+; ~~~~~~~~
 ;
-;     %! exec dir
-;     %g temp dir
-;     %j data dir
-;     %k ctrl dir
-;     %z text dir
+; A "mail processor" can modify or reject any message (body or header)
+; or the list of recipients (envelopes) for any SMTP-received mail.
 ;
-;     %o sysop name
-;     %q system QWK-ID
-;     %v Synchronet version
-;     %? platform
-;     %% percent symbol
+; Each line of this file that doesn't begin with a semicolon (comment)
+; is a mail processor command-line that will be run for every incoming
+; SMTP mail message.
 ;
-; Format of recipient list file is (3 lines per recipient):
+; These instructions are for the Synchronet Mail Server (mailsrvr.c)
+; revision 1.289 and later.
 ;
-; line 1: usernumber or 0 if external recipient
-; line 2: requested recipient address (e.g. "sysop@yourbbs.com")
-; line 3: actual recipient address or "#usernumber" if being delivered locally
-; ...repeating for additional recipients
+; Command-line Specifiers
+; ~~~~~~~~~~~~~~~~~~~~~~~
 ;
-; mail processing commands follow:
+; Mail processor command-lines use command-line specifiers (i.e. macros
+; or variables) to represent dynamic information.
+; 
+; Command-line specifiers (macros/variables) available:
+;
+;     %m = mail message (header and body text) path/filename
+;     %l = recipient list path/filename
+;     %e = processing error path/filename (put error text in this file)
+;
+;     %h = sending SMTP server's host name
+;     %i = sending SMTP server's IP address
+;
+;     %u = authenticated user number (0=unauthenticated)
+;
+;     %! = Synchronet exec directory
+;     %g = Synchronet temp directory
+;     %j = Synchronet data directory
+;     %k = Synchronet ctrl directory
+;     %z = Synchronet text directory
+;
+;     %o = sysop name
+;     %q = system QWK-ID
+;     %v = Synchronet version
+;     %? = platform
+;     %% = percent symbol
+;
+; Rejecting/Ignoring Mail
+; ~~~~~~~~~~~~~~~~~~~~~~~
+; 
+; If the mail processor deletes the mail message (%m) or recipient list (%l)
+; files, the mail message will be silently ignored. The sending SMTP server
+; will not receive any error or failure indication.
+;
+; If the mail processor creates a processing error (%e) file (1 or more bytes)
+; the mail message will be rejected by the SMTP server with the error message
+; contained in the processing error file and an SMTP error response of 554.
+;
+; Processing Error File
+; ~~~~~~~~~~~~~~~~~~~~~
+;
+; If the processing error file (%e) is created by the mail processor, it may
+; contain simple error text (one or more lines) or SMTP error codes (with
+; proper SMTP mutli-line response formatting) if the default STMP error
+; response (554) is not desirable.
+;
+; Mail Message Format
+; ~~~~~~~~~~~~~~~~~~~
+;
+; The mail message file (%m) is a plain ASCII text file in RFC 821 format
+; containing the full message header and body as received by the SMTP server.
+;
+; Recipient List Format
+; ~~~~~~~~~~~~~~~~~~~~~
+;
+; The recipient list is an ini-formatted file with a separate ini section
+; (e.g. "[#]") for each recipient envelope.
+;
+; Each section (recipient) supports the following keys:
+;
+; Recipient = original destination address
+; RecipientExt = user record number, if addressed to a local user
+; RecipientNetType = deliver-to network type (0=none, 4=QWK, 5=Internet)
+; RecipientNetAddr = deliver-to network address
+; 
+; Example recipient entries:
+;
+; Example for a local mail recipient:
+; [0]
+; Recipient=rob@synchro.net
+; RecipientExt=1
+;
+; Example for an externally-relayed mail recipient:
+; [1]
+; Recipient=rob@somewhere.org
+; RecipientNetType=5
+; RecipientNetAddr=rob@somewhere.org
+;
+; Example for a forwarded mail recipient:
+; [2]
+; Recipient="dr. seuss"@synchro.net
+; RecipientExt=3
+; RecipientNetType=5
+; RecipientNetAddr=santakrooz@yahoo.com
+;
+; Example for a QWKnet-routed mail recipient:
+; [3]
+; Recipient=digital.man
+; RecipientExt=1685
+; RecipientNetType=4
+; RecipientNetAddr=FREEBSD
+;
+; Mail Processing commands follow:
+; ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+;
+; Hint: Remove semicolon to activate a mail processor command-line.
 ;
 ; echo This is a sample mail process command. >> %m
+; grep -i penis %m > %e
+; %!jsexec somescript %m %l %e
\ No newline at end of file