Getting Intimate With PHP's Mail() Function - The Mail() Function Explained

(Page 2 of 5 )

The mail() function accepts three required values and one optional value. It returns a value indicating success or failure. The email address of the recipient (or To: field), the subject of the message (or Subject: field), and the message body can all be specified through parameters. An optional string containing extra headers can also be specified.

The signature of the mail function looks like this:

bool mail(string msgTo, string msgSubject, string msgBody, string extraHeaders);

To send a message, you simply fill in the parameters. This example uses literal strings to illustrate the general usage of the function. The first parameter specifies the email address we are sending mail to. The second is the message subject. I used the third optional parameter to set the "From:" header to an address where I wanted replies to go and added a "X-Mailer:" header to help mail administrators identify the message as originating from an automated source.

When you create a custom header string, remember to separate each additional header with a linefeed (\n), otherwise the message text may become garbled. Messages sent through the mail() function are sent in plain text:

mail ( "knoblock@att.tld", "Use PHP Everyday", "Don't forget to floss and use PHP everyday!", "From: hygienist@phphelp.tld\nX-Mailer: My PHP Script\n");

Most of the time you won't be specifying these values using literal strings. Instead you will use variables. You may want to obtain these values from an included PHP script fragment (an "initialization file"), or from a form submission.

It's likely you'll want to use values submitted by a form or those generated programmatically to send a message. In that case we substitute string variables for the literal strings used in the previous example:

mail ($strMailTo, $strSubject, $strBody, $strXHeaders);

Adding Extra Header Information
As I mentioned, the mail() function allows you to specify additional header fields to be added to the message header. One use for the extra headers is to identify the message as having been generated programmatically. Any script that generates mail can be thought of as a "remailer." Often, it is useful for a form to send mail that appears to come from the person submitting the form. One such use is when setting up a form that subscribes a user to a mailing list.

The following code rewrites the From: field to the user's email address and adds an X-Header identifying the mail as being sent from your custom remailer script. Identifying mail as coming from your script gives administrators a heads up that mail is coming from an automated source. If there should be a problem with mail generated by your script then they can easily diagnose where and when the mail was sent from. I use the phpversion() function to identify the message as coming from a PHP script (as the PHP manual shows):

mail($list_request, "Subscribe", "Subscribe", "From: $email_address\nX-Mailer: PHP/" . phpversion());

Some list servers require that the user's first and last names be available in the From: field. To satisfy them, add form variables for the names into the From: field in the extra headers. It's necessary to "escape" the double quotes within a double quote context. This is accomplished by prefixing (or "escaping", which is the fancy term for protecting a character from misinterpretation) the quotes surrounding the first and last names with the backslash character. The email address is enclosed by angle brackets to help differentiate it from the surrounding text, as is usual practice in net email.

$from = "From: \"$first_name $last_name\" <$email_address>\nX-Mailer: PHP/" . phpversion();

mail($list_request, "Subscribe", "Subscribe", $from);

When to Use the Mail Function
Having such a simple and uncomplicated function for sending mail is useful when a script must send several messages. It's also nice to be able to communicate with the mail program without worrying about the command syntax or security measures required to execute a Unix mail program. Although the interface to sendmail or qmail is standardized, using the mail function protects your script to a degree from any changes to sendmail that an administrator might make.

Using the mail() function means that you do not have to create your own function for sending mail or duplicate code inline. The following script gives an example of using more than one mail() function in a script to notify the administrator when a form submission is made and at the same time, respond to the user via email.

Please keep in mind this is just a sketch showing what is possible. It is not a working example:

if ($notify)
{
// notify admin
$mailTo = "admin@some.com";
$msgSubject = "Downloading MediaKit";
$msgBody = "$name, $company, $address, $email_address, $demographics";
$xHeaders = "From: $email_address\nX-Mailer: PHP/" . phpversion();

mail ($mailTo, $msgSubject, $msgBody, $xHeaders);
}

// thank customer
$mailTo = $email_address;
$msgSubject = "Thank You for Downloading our MediaKit";
$msgBody = "Please feel free to contact us if you have any questions or desire a quote.\nThank You.\n";
$xHeaders = "From: admin@some.com\nX-Mailer: PHP/" . phpversion();

mail ($mailTo, $msgSubject, $msgBody, $xHeaders);

Next: Talking to Sendmail >>
 

More PHP Articles
More By Steve Knoblock

Comments On: Getting Intimate With PHP's Mail() Function

· Very interesting article, however I was really hoping it would cover how to deal...   >>> Post your comment now!