Preparing Your Environment

Before you begin integrating email with your applications, you'll need to make sure that you've correctly configured your environment so that ColdFusion can communicate with your selected email server.

Figure 11.1 shows you the email configuration page in the ColdFusion Administrator.

Figure 11.1. Email configuration page of the ColdFusion Administrator.

In the Mail Server text box, you enter the Internet Protocol (IP) address of the mail server that you want ColdFusion to use to send the email from your application. It's important that you understand that ColdFusion itself is not a mail server. All ColdFusion does is take the messages that your application is sending and forward them to the mail server that you have specified for processing.

In some cases, the mail server that you are using in conjunction with ColdFusion might exist on the ColdFusion Server itself. In these cases, it's correct for you to enter the IP 127.0.0.1 loopback address as the mail server address. This tells ColdFusion that the mail server you are using is on the same physical machine as ColdFusion itself.

If the mail server you are using is physically separate from ColdFusion, make sure that you enter the IP address rather than the host name of the mail server. This enables ColdFusion to continue processing mail from your application in the event that your network is having Domain Name System (DNS) problems.

In situations in which your mail servers are part of a cluster, you'll need to load balance the traffic sent to them. In addition, in situations in which you don't control the mail server that you are using with ColdFusion, it might be necessary to use the host name of the mail machine. Using the host name works fine, but you must be aware that if DNS problems arise, ColdFusion might be unable to send mail until the problems are resolved.

In the Server Port text box, unless your network administrator has explicitly directed you to use a specific port to communicate with your mail server, you'll want to use 25. This is the default Simple Mail Transfer Protocol (SMTP) port.

In the Connection Timeout (seconds) field, you usually can leave the timeout set to the default (60 seconds). If you know in advance that you have either a slow connection between ColdFusion and the mail server or a mail server that takes a long time to validate connections, you might need to tweak this value accordingly.

If you leave the Spool Interval (seconds) text box with a value of 15 seconds, which is the default, you are generally fine for most applications. This interval determines how long the executive process waits between checks of the mail spool to determine if mail needs to be processed. You can save a little overhead by raising this value, but be careful not to set it too high. Doing so can cause the spool to accumulate a lot of messages waiting to be sent. Unfortunately, having too much unprocessed mail in the spool has, in the past, caused performance problems with CFMAIL.

Check the Verify Mail Server Connection check box if this is the first time that you've attempted to set up a mail server through your ColdFusion Administrator. Checking this box forces ColdFusion to attempt a handshake with the mail server after you submit the values on this page. You will be told in an onscreen message whether ColdFusion's attempt to connect with the mail server was successful.

In the event that you get a "Connection Verification Failed!" message when you submit the form, go back to the Mail Server text box and make sure that you've indeed entered the correct IP address of your mail server. If you know that the IP address you've entered is correct, attempt to verify the network connection between the ColdFusion Server and the IP address you've entered. You can do this by bringing up a command prompt or terminal window on the ColdFusion Server and pinging the IP address that you've entered for the mail server. If you get a message indicating that the IP address is unreachable, you might need to verify the IP address and network configuration again with your network administrator.

At this point, it's important to stop for a moment and discuss a scenario. Some developers write code that must exist on a ColdFusion Server that is shared by multiple applications. In many of these cases, you might not have access to the ColdFusion Administrator. Even if you do have access to the ColdFusion Administrator, you might not have the right to add or edit the mail server that ColdFusion uses by default. Fortunately, this doesn't mean that you can't make use of CFMAIL.

The developers of the ColdFusion Application Server took this into account when developing the product and have made it possible for you to specify the mail server to which you want to connect. You can also specify the port on which you want to connect, the username/password you need to use, and many other parameters. All these parameters can be specified directly from within the CFMAIL tag itself. In the event that you cannot configure the ColdFusion Administrator for the mail server you need to use, you can use the parameters of CFMAIL to specify these elements. We discuss the details of how to do so later in this chapter.

Toward the bottom of the Mail Settings page in the ColdFusion Administrator, you will notice two items under Mail Logging Settings. These two items enable you to have some control over the types of messages that ColdFusion will log about the mail that it is automatically forwarding to the mail server.

Figure 11.2 shows the Mail Logging Settings options available in the ColdFusion Administrator.

Figure 11.2. Mail Logging Settings options in the ColdFusion Administrator.

The first setting you can control is the severity of messages that are written to your log files. When you make use of CFMAIL in any of your applications, you'll want to keep track of when things don't go as expected so that you can troubleshoot and fix problems as quickly as possible.

The Error Log Severity drop-down list enables you to control the types of messages that are written to the special mail.log file. This file appears in your log directory after you begin using CFMAIL. Should your application have a problem sending email, any messages about the nature of the problem are recorded in this mail.log file. It's a good idea to check this and all log files frequently and examine and fix any errors that are reported. Generally, a healthy application should have log files that grow very slowly over time. If you begin to notice a high number of errors being recorded in any log file, that's a good indication that something unexpected has occurred and the problem needs to be investigated and solved.

The next choice you have is whether you want ColdFusion to record the content of all messages that it sends. Usually, on production servers, this is a bad idea. It requires additional overhead to perform this task; in addition, depending on the volume of mail that your server sends daily, it may require a large amount of disk space. Unless you have a very specific reason for needing to record the content of all the messages you are sending, you'll probably want to leave this setting turned off.

If you are using ColdFusion to enable users of your system to construct web-based email messages, there might be privacy concerns that you'll need to consider before deciding to log the content of the email messages being sent. If you do make the decision to record the content of these messages and the messages were constructed by one of your users, you'll likely need to tell them that their communications are being recorded.

After you've got your environment properly configured and have verified that your ColdFusion Server can communicate with the mail server you have chosen, you can begin exploring the ways in which you can implement automated emailing in your applications.