Troubleshooting ColdFusion Mail

To understand where to look when things go wrong with mail services, we need to inspect what ColdFusion does when it sends email.

The < cfmail > command generates a mail spool file containing information about the server to use, recipients, sender, and so on, and places it in the cfusionmx7\mail\spool directory. A special low-level thread sweeps the spool directory every 15 seconds, sending any spool files to the SMTP server specified in the mail headers.

NOTE

A mail spool file is a simple text file specifically formatted for an SMTP server. It starts with a series of mail headers and finishes with the body of the mail message.

If the specified SMTP server refuses to send the message, or if ColdFusion is unable to contact the SMTP server, an error is logged, and the spool file is moved to the cfusionmx7\mail\undelivr directory.

You can set mail error-logging options in ColdFusion Administrator. Your SMTP server's log may be another place to look for enlightenment.

CAUTION

SMTP servers have a multitude of configuration options. A common cause of undelivered mail is anti-relay measures on the SMTP server. This can prevent unauthorized senders from using the mail server at all. Depending on your environment, you might need to ensure that the ColdFusion server is authorized to use the SMTP server and that the sender field has a correctly formatted email address, among other things.

The ColdFusion log files and your SMTP server's transaction log are good places to look when email inexplicably appears in the undelivr directory.

Undelivered mail can be reprocessed by simply moving the spool file from cfusionmx7\mail\undelivr back to cfusionmx7\mail\spool . This procedure can be done programmatically through ColdFusion or manually by an administrator. You can automate this by scheduling a process to scan the undelivr directory and move any files back to the spool directory. However, malformed spool files or files with incorrect header information (such as a bad email address) may be in the undelivr directory for a very good reasonthat is, they are undeliverable!

Scheduling periodic processes was covered in Chapter 40, "Scheduling and Event Execution."

CAUTION

The message numbers returned by < cfpop > are relative to the position of the email messages in the POP message queue. Message numbers should not be stored as unique identifiers because they change whenever email is deleted from the mailbox queue. They should be used immediately because of the transient nature of POP mail storage.