LISTSERV at Work
LISTSERV Tech Tip

Q: How can I capture copies of incoming messages before they are processed by LISTSERV?

List owners sometimes hear from subscribers who wonder why the formatting of their messages doesn't look like they intended or why certain commands didn't go through. To troubleshoot these types of situations, you can use a special debugging option to tell LISTSERV to keep copies of incoming messages before processing them. This allows you to compare the original version of the message, before LISTSERV processed it, to the version that was distributed, so that you can see if these formatting changes were introduced by LISTSERV.

Note, however, that having LISTSERV keep copies of all incoming messages will result in files building up in the spool directory. If left unchecked, this can eat up disk space very quickly and reduce the efficiency of LISTSERV. For this reason, it's recommended to only enable this option for as long as needed to capture the problematic messages. Don't leave this option enabled for long periods of time if it can possibly be avoided.

Capturing the Messages

With that understood, you can capture copies of incoming messages to LISTSERV as follows:

1. Before the next time one of the messages that you want to capture is going to be sent, go to "LISTSERV Command" under "Server Administration" in the LISTSERV web interface. Then issue the following command:

DEBUG FLAGS +KEEP_JOBFILES

This will tell LISTSERV to store all incoming messages in .deleted files in the listserv\spool\ directory before processing them.

2. Wait for the message to be sent.

3. Verify that whatever problem you are troubleshooting has, indeed, happened again.

4. Issue the following command:

DEBUG FLAGS -KEEP_JOBFILES

This will stop LISTSERV from creating additional .deleted files.

Hopefully, there are only a small number of .deleted files with a creation time that matches the time the error occurred. If so, you can view their content as described below until you find the troublesome message.

You can delete any .deleted files that were generated before or after the error occurred. LISTSERV won't use them for anything. You don't need to restart LISTSERV to do this.

Reading .DELETED Files

The files will be located in the listserv\spool\ directory (under Windows) or the ~listserv/spool/ directory (under Unix). Note, however, that the files are encoded, so you can't simply open them in Notepad or a similar program.

Instead, they can be viewed by using using the "jobview" command-line executable, which should normally also be found in the spool directory.

To view a message, go to the spool directory from the Windows or Unix command line and enter:

jobview xxxxxx.deleted

Replace "xxxxxx.deleted" with the actual name of the .deleted file. If the message is too long to fit onto a screen, you can capture the contents of the .deleted file to a plaintext file by entering:

jobview xxxxxx.deleted > xxxxxx.txt

As above, replace "xxxxxx.deleted" with the name of the actual .deleted file, and "xxxxxx.txt" with the name of the file that you want to store the plaintext version in.

If you are using LISTSERV for Unix and can't find jobview, issue the following command from the "listserv" user's home directory:

make jobview

This should compile a copy of jobview for you.

When dealing with multiple .deleted files, it can be helpful to keep everything organized and to have the two files have the same name with a different extension – for example, 0077.deleted and 0077.txt. This also makes it easier to match up the .txt files with entries in the LISTSERV log file.

Although the output is plain text, keep in mind that you will be looking at the "raw code" of the email message, including its full headers, HTML code (if the message used HTML for formatting) and any attachments, so it will be encoded. This can make for a difficult reading experience if you aren't used to it.

In general, the best place to start is to look at the message headers. The "From", "Date", and "Subject" lines should allow you to determine if you've found the correct message.

Matching Up .DELETED Files with LISTSERV Log File Entries

Once you've found the .deleted file containing the message that you're interested in, you can open the LISTSERV log file from the date on which it was created and search for the numerical code found in the .deleted file's name. For instance, for a file named 0076.DELETED, search for 0076 in the log file. If the message was sent to listserv@... and contained some commands, you might see something like:

29 Mar 2021 15:14:57 Processing file 0076 from MAILER@LIST.EXAMPLE.COM
29 Mar 2021 15:14:57 -> Decoding MIME message parts...
29 Mar 2021 15:14:57 Rescheduled as: 0077
29 Mar 2021 15:14:57 Processing file 0077 from LISTSERV@LIST.EXAMPLE.COM
29 Mar 2021 15:14:57 From chris.q.public@EXAMPLE.COM: help
29 Mar 2021 15:14:57 From chris.q.public@EXAMPLE.COM: thanks
29 Mar 2021 15:14:57 To chris.q.public@EXAMPLE.COM: You're welcome!
29 Mar 2021 15:14:57 Sent information mail to chris.q.public@EXAMPLE.COM

Note the "Processing file 0076" at the top of this log file entry, which refers to the number found in the .deleted file's name.

This process can also be reversed. If you find some entries in the LISTSERV log file and want to find the corresponding .deleted file, then find the number in the "Processing file" line and look for the .deleted file with the same name.

A little caution is necessary. Note that in the above log file excerpt, the message was first received in file 0076.

29 Mar 2021 15:14:57 Processing file 0076 from MAILER@LIST.EXAMPLE.COM

LISTSERV then read the message, re-encoded it in a way that would be easier for it to process, and processed it again:

29 Mar 2021 15:14:57 -> Decoding MIME message parts...
29 Mar 2021 15:14:57 Rescheduled as: 0077
29 Mar 2021 15:14:57 Processing file 0077 from LISTSERV@LIST.EXAMPLE.COM

In cases like this, you will want to look at the initial version received (0076.DELETED in this case) and not the "respooled" version.

Comparing a .DELETED File's Contents to the Version Distributed by LISTSERV

It's difficult to compare the contents of a .DELETED file to a message received in your email program just by looking at them. As noted above, you'll be looking at the raw code of the email when you look at the .DELETED file, with the HTML code visible and attachments encoded, while your email program normally would automatically decode the message and display it to you in a more friendly fashion.

Some email programs and services do allow you to view the raw code version of email messages. For instance, in Gmail, you can open a message and go under the ⠇ menu to "Show Original", and in Apple Mail you can go under "View" to "Message"/"Raw Source".

If you are not using an email program that has this feature, then another option is available if the email list has archives. In that case, you can find the message in the location given in the "Notebook=" directory.

The notebook files typically will have names like listname.LOGyyyymmw, where "listname" is the name of the actual email list, "yyyy" is the year it was distributed by LISTSERV, "mm" is the two-digit month, and "w" is a letter corresponding to which week of the month the message was distributed. You can use this naming convention to find the file containing the message. Notebook files are plaintext, so you can open them in Notepad or any other text editor.

Each message in the archives begins with a line of 73 equal signs. From there, searching for the "From" address, the "Date" header's contents, or the subject as seen in the .DELETED file should allow you to find the message of interest.

In interpreting the contents of the notebook files, be aware that LISTSERV discards many of the message headers when adds it to the archives.

By being able to compare the email message before and after it was processed by LISTSERV, you'll find out if the changes were introduced by LISTSERV or if the problem is associated with the sender's email system. You can then use this information and take additional actions to remedy the underlying issue.


Got Feedback?

Let us know about topics and tasks you'd like to see covered in future tech tips.

Get in Touch

Next Steps


© L-Soft 2021. All Rights Reserved.




Powered by LISTSERV Maestro