9.4 Advanced LISTSERV Applications Using DISTRIBUTE
Depending on your specific needs, it is possible for sites to "get creative" and use traditional LISTSERV lists as "back-ends" in conjunction with DISTRIBUTE jobs to handle bounces in the same way they are handled for a regular LISTSERV list, without ever using the list itself for posts.
Let's say that, to begin with, you collect addresses from a guestbook web page that you've set up for your company. You want to send out periodical updates to these people using RFDR "DISTRIBUTE" jobs but you know that you are going to have the usual 15-20% or more bad addresses from typos, pranksters, and plain old attrition. How do you find the bouncing addresses so you can purge them from your database without having to read each bounced message and determine what address actually bounced?
Simply create a traditional list with the appropriate error handling setting desired (see other sections of this manual and of the List Owner's Manual for LISTSERV for more information). Set "Change-Log= Yes" and "Auto-Delete= Yes,Full-Auto,Delay(0)" in the list's header ("Change-Log" requires LISTSERV 1.8d and later). Use an ADD IMPORT job as detailed in chapter 4.3 of the List Owner's Manual to add all of the addresses from your database to the list.
Then, in your RFDR job, set the following in the FROM= option of the DISTRIBUTE command line:
DISTRIBUTE MAIL FROMfirstname.lastname@example.org PW=XXXXXXXX
where listname is the name of the list created. For instance, if the list was named bouncelist1 and the LISTSERV host name was LISTSERV.EXAMPLE.COM, then the DISTRIBUTE command would be as follows:
DISTRIBUTE MAIL FROMemail@example.com PW=XXXXXXXX
Once you have the bounce list set up (and we'll continue to use our bouncelist1 example), you simply check the BOUNCELIST1.CHANGELOG file for a listing of addresses LISTSERV has auto-deleted from bouncelist1 since you sent out your RFDR job. You can then use this changelog file to update your database and clean out the bad addresses.
Do keep in mind, however, that in order for LISTSERV to take action on permanent bounces that come to the owner-bouncelist1 address and are, furthermore, in a format understandable by LISTSERV, the bouncing address(es) must also be listed as subscribers in the back-end bouncelist1 list (so do not forget to bulk add the addresses before sending the DISTRIBUTE job, as explained above).
To take this a step further, you could also use this same back-end bounce processing list as a front-end list to handle automatic subscribe and unsubscribe requests for each mailing, allowing for total flexibility for both yourself and the customers being mailed to.
9.4.1 "List-free" bounce processing for one-shot lists
This feature is not available for LISTSERV Lite or for LISTSERV Classic/Classic HPO running on VM.
You can bounce-process a one-shot list without needing a back-end list for the bounces to come back to (as outlined above).
To use the "list-free" feature, you create and send a standard DISTRIBUTE MAIL-MERGE job with the FROM= address set to OWNER-NOLIST-xxx@hostname (where 'xxx' can be anything and 'hostname' is LISTSERV's host name), for instance OWNER-NOLIST-MYDIST@LISTSERV.MYHOST.COM. While 'xxx' can be anything, OWNER-NOLIST@whatever doesn't work--you must provide '-xxx'. Within the job you then use PROBE for each address in the manner documented above.
Note: This feature requires that you send the job as a mail-merge message using DISTRIBUTE MAIL-MERGE, even if the job is not a mail-merge job. The feature does not work with DISTRIBUTE MAIL. In addition, you MUST have EMBEDDED_MAIL_MERGE enabled, and you must use SMTP "workers" (i.e. you must have SMTP_FORWARD_n= variables set in your site configuration file so that LISTSERV sends mail to its outbound mailers in asynchronous mode).
After sending the job, you get a NOLIST-xxx.CHANGELOG in LISTSERV's A directory with entries for every bounce. (In our example above, this file would be called NOLIST-MYLIST.CHANGELOG.)The entries read BOUNCE followed by the e-mail address. As there is no monitoring and no decision to delete, the entry does not read AUTODEL, and thus bounce reporting for "list-free" DISTRIBUTE jobs is passive. By definition, however, you can't monitor one-shot jobs; monitoring (if desired) must be provided by collating all the one-shot jobs into a big monitoring database, or something similar (all jobs from client such and such, etc.).
Note: If you are running under unix with sendmail, you will have to patch sendmail in order for it to properly accept and route bouncing probe messages. As a convenience, L-Soft provides third-party sendmail patches for this purpose on its FTP site (in https://ftp.lsoft.com/listserv/unix/CONTRIB). Please be aware that L-Soft did not write and does not support these patches in any way; they are strictly for use at your own risk and you must contact the author(s) of the patches for help with them.
It is sometimes desirable to send mail to a LISTSERV list with Send=Editor,Confirm, Send=Owner,Confirm, or Send=address,Confirm, and have it go out immediately, rather than wait for the editor to confirm it. Thus, there needs to be a mechanism for password-confirming a posting to a list as a substitute for the e-mail confirmation handshake.
To provide this mechanism, the DISTRIBUTE POST command is available. The syntax is based on the existing DISTRIBUTE MAIL command, with certain important differences:
- The verb is POST instead of MAIL. Data and recipient are supplied as usual. For example, TO xxx, TO DD=xxx, or implied DD.
- Only one recipient (the address of the list to which you are posting) is allowed in the TO DD; anything else is will generate an error message. Automated scripts should guard against supplying more than one recipient.
- Although an FQDN is required in the TO DD, the hostname of this recipient is assumed to be an alias for the local host, and is ignored. The local-part must be a valid, existing list. An error message will be generated if this is not the case.
- The PRE-APPROVED=NO|YES option becomes available to DISTRIBUTE POST. The default is NO and it then works like a DISTRIBUTE MAIL job with the list as sole recipient, except that it is more efficient. You must be a list owner to use PRE-APPROVED=YES. PRE-APPROVED=YES cannot be used with DISTRIBUTE MAIL and will generate an error message if so used. If the list is moderated, and the sender address is not an editor, the e-mail sent in this way will be submitted for moderation. To clarify: this replaces confirmation not moderation approval. Make sure that the poster's address (in the 'From:' line) is authorized to post to the list, or the message may be rejected or forwarded to the moderator. PRE-APPROVED=YES authenticates the origin of the message, but does not bypass the normal authorization steps.
- DISTRIBUTE POST is not available under VM.
- Distribution options are ignored, since DISTRIBUTE does not deliver the message at this time but passes it on to the list posting mechanism.
It is important to understand that DISTRIBUTE POST is just a submission system. The posting may be processed immediately, it may be delayed until the time specified in the list header, it may be sent to the moderator if the owner is not allowed to post to the list (perhaps not very common, but there are such lists), the list could be on hold, a virus could be detected (if you did not use AV=YES), etc.
Following is a list of the DISTRIBUTE options supported or partially supported with DISTRIBUTE POST.
- CANON=, AV=, PRE-APPROVED=
- DD=: TO DD must refer to a list.
- DEBUG=YES: The job will be executed with all verifications, but in the end the message will not be posted (this is the primary purpose of DEBUG=YES). The secondary purpose, to receive a report showing the intended message routing, number of recipients and so on, is not supported since DISTRIBUTE POST always sends 1 local message and forwards 0 jobs to other servers.
Other options are ignored as long as the syntax is correct. If there is a syntax error, the job fails.