{{toc numerate=1}}
PHPMailer is a PHP class for PHP that provides a package of functions to send email. The two primary features are sending HTML Email and e-mails with attachments. PHPMailer supports nearly all possibilities to send email: ##mail()##, ##Sendmail##, ##qmail## & direct to SMTP server. You can use any feature of SMTP-based e-mail, multiple recipients via to, CC, BCC, etc. In short: PHPMailer is an efficient way to send e-mail within PHP.
As you may know, it is simply to send mails with the PHP mail() function. So why use PHPMailer? Isn't it slower? Yes that's true, but PHPMailer makes it easy to send e-mail, makes it possible to attach files, send HTML e-mail, etc. With PHPMailer you can even use your own SMTP server and avoid Sendmail routines used by the ##mail()## function on *nix platforms.
This tutorial explains how to implement the class into your script or website and how to build an e-mail application. If you just want to send simple e-mail and you have no problems with the ##mail()## function, it's suggested that you continue to use ##mail()##, instead of this class.
===First time===
For those who have not used PHP's ##mail()## function before, this section will provide information about email and e-mailing in general, in addition to explaining how to get started with PHPMailer.
Before continuing, please be sure that PHPMailer is installed correctly. If you feel uncertain, please read the installion instructions that accompany the package. If you're still not sure, you can verify that you've installed PHPMailer correctly with this little script:
%%(php)
<?php
require 'PHPMailerAutoload.php';
$mail = new PHPMailer();
?>
%%
Save it as a PHP document in the same directory where you've saved class.phpmailer.php. If no errors result from running the script, your installation has been done correctly. If you switched error messages and warnings off, then go ahead and set it on; refer to your PHP manual for more on this topic.
This snippet of code is also the start of any use of PHPMailer. ##require 'PHPMailerAutoload.php';## includes the source code of the class and ##$mail = new PHPMailer();## creates a new instance of the class the class as $mail. All features, functions and methods of the class maybe accessed via the variable (object) $mail.
Merely creating an instance of the class is only the first step, of course. Let's go ahead and send out the first mail. For this you'll require the basics: An recipient address, a from address, a subject and the text of the message (called "mail-body" or simply "body" for short).
You will also need to select a method of delivering the message. We need a program to communicate with an SMTP server which, in turn, sends the mail out to the internet. In the *nix world, Sendmail is very popular and used widely.
PHPMailer provides several methods of sending mail. It's best to start with SMTP, though (as mentioned above)_ the ##mail()## function, ##Sendmail## or ##qmail## are also possible. When using SMTP, you'll need a valid SMTP server; this may well be the same one that you use in your personal mail client.
Having gathered the necessary information to send your first e-mail, you'd use that information in place of the example information provided here:
%%(php)
<?php
require 'PHPMailerAutoload.php';
$mail = new PHPMailer();
$mail->IsSMTP(); // telling the class to use SMTP
$mail->Host = "smtp.example.com"; // SMTP server
$mail->From = "from@example.com";
$mail->AddAddress("myfriend@example.net");
$mail->Subject = "First PHPMailer Message";
$mail->Body = "Hi! \n\n This is my first e-mail sent through PHPMailer.";
$mail->WordWrap = 50;
if(!$mail->Send()) {
echo 'Message was not sent.';
echo 'Mailer error: ' . $mail->ErrorInfo;
} else {
echo 'Message has been sent.';
}
?>
%%
Save this as a php file and change the values to your values, of course. Here is an explanation of what each stanza in this script does:
##$mail->IsSMTP();##
This sets up STMP-Server as method to send out email(s).
##$mail->Host = "smtp.example.com";##
Setting smtp.example.com as the SMTP server. Just replace it with your own SMTP server address. You can even specify more then one: just separate them with a semicolon (;): ##"smtp.example.com;smtp2.example.com"##. If the first one fails, the second one will be used, instead.
Enter the address that the e-mail should appear to come from. You can use any address that the SMTP server will accept as valid.
##$mail->From = "from@example.com";##
If displaying only an e-mail address in the "From" field is too simple, you can add another line of code to give the address an associated name. This will add 'Your Name' to the from address, so that the recipient will know the name of the person who sent the e-mail.
The following line
##$mail->FromName = "Your Name";##
[Andy Prevost:] with PHPMailer version 5.0.0, you can now achieve this with one command:
##$mail->SetFrom("from@example.com","Your Name");##
The following will add the to address, the address to which the e-mail will be sent. You must use a valid e-mail here, of course, if only so that you can verify that your PHPMailer test worked. It's best to use your own e-mail address here for this initial test. As with the "From" field, you may provide a name for the recipient. This is done somewhat differently:
##$mail->AddAddress("myfriend@example.net","Friend's name");##
##$mail->AddAddress("myfriend@example.net");##
Setting the subject and body is done next. ##$mail->WordWrap = 50;## is a feature of PHPMailer to word-wrap your message limiting all lines to a maximum length of X characters, even if not set as body= .... Admittedly, there's not much point in wrapping the text in a message as brief as the one in this example.
Finally, we send out the e-mail, once all necessary information has been provided. This is done with ##$return = $mail->Send();##. In this example script, it's combined with an error message; if ##Send()## fails, it'll return false and you can catch it and display an error message. This is done in the last lines. Or, in case of success, it displays a kind of "done " message.
===Using Attachments===
Sending plain text e-mails is often insufficient. Perhaps you need to attach something to your mail, such as an image or an audio file. Or perhaps you need to attach multiple files.
There are two ways of attaching something to your mail: You can simply attach a file from the filesystem or you can attach (binary) data stored in a variable. The latter is called Stringattachment. This makes it possible put extract data from a database and attach it to an e-mail, without ever having to actually save it as a file.
===File Attachments===
The command to attach a file can be placed anywhere between ##$mail = new PHPMailer();## and ##!$mail->Send();## and it's called ##AddAttachment($path);##. This single line will add the attachment to your mail.
$path is the path of the filename. It can be a relative one (from your script, not the PHPMailer class) or a full path to the file you want to attach.
If you want more options or you want to specify encoding and the MIME type of the file, then you can use three more parameters, all of which are optional:
##AddAttachment($path,$name,$encoding,$type);##
##$name## is an optional parameter, used to set the name of the file that will be embedded within the e-mail. The person who will recieve your mail will then only see this name, rather than the original filename.
##$encoding## is a little more technical, but with this parameter you can set the type of encoding of the attachment. The default is base64. Other types that are supported include: 7bit, 8bit, binary & quoted-printable. Please refer to your SMTP documentation about encoding and the differences between types. In general, mail servers will convert encodings they don't want to handle into their preferred encoding type.
##$type## is the MIME type of the attached file. Content types are defined not necessarily by file suffixes (i.e., .GIF or .MP3), but, rather, a MIME type (MIME = Multipurpose Internet Mail Extensions) is used. This parameter makes it possible change the MIME type of an attachment from the default value of application/octet-stream (which works with every kind of file) to a more specific MIME type, such as image/jpeg for a .JPG photo, for instance.
===String Attachments===
String attachments have been supported since PHPMailer version 1.29. This method works much like AddAttachment(), and is called with ##AddStringAttachment($string,$filename,$encoding,$type)##. The string data is passed to the method with the first parameter, $string. Because the string will become a standard file (which is what the attachment will be when received via e-mail), the ##$filename## parameter is required. It's used to provide that filename for the string data.
The rest is just the same as described in detail above.
So, why use ##AddStringAttachment## instead of ##AddAttachment##? Is it for text-only files? No, not at all. It's primarily for databases. Data stored in a database is always stored as a string (or perhaps, in the case of binary data, as as a BLOB: Binary Large OBject). You could query your database for an image stored as a BLOG and pass the resulting string to the ##AddStringAttachment##.
===Inline Attachments===
There is an additional way to add an attachment. If you want to make a HTML e-mail with images incorporated into the desk, it's necessary to attach the image and then link the ##<img src="cid:CID" />## tag to it. For example, if you add an image as inline attachment with the CID my-photo, you would access it within the HTML e-mail with ##<img src="cid:my-photo" alt="my-photo" />##.
In detail, here is the function to add an inline attachment:
##$mail->AddEmbeddedImage(filename, cid, name);##
By using this function with this example's value above, results in this code:
##$mail->AddEmbeddedImage('my-photo.jpg', 'my-photo', 'my-photo.jpg ');##
For more Information about HTML Email, see the section Using HTML E-Mail.
===Handling Attachments===
If you want to attach multiple files (or strings), just call ##AddAttachment()## or## AddStringAttachment()## multiple times. All attachments (file, string, and inline) may be stripped from an e-mail by invoking ##ClearAttachments()##.
===Using HTML Email===
Sending out HTML e-mail is a simple enough task with PHPMailer, though it can require significant knowledge of HTML. In particular, mail clients vary greatly in their rendering of HTML e-mail, with some refusing to show it entirely. For those mail clients which are not able to display HTML, you can provide an alternate e-mail body containing the message as plain text.
First we'll create a basic HTML message:
%%(php)
<?php
require 'PHPMailerAutoload.php';
$mail = new PHPMailer();
$mail->IsSMTP(); // telling the class to use SMTP
$mail->Host = "smtp.example.com"; // SMTP server
$mail->From = "from@example.com";
$mail->AddAddress("myfriend@example.net");
$mail->Subject = "An HTML Message";
$mail->Body = "Hello, <b>my friend</b>! \n\n This message uses HTML entities!";
?>
%%
It's as easy as creating a plain text e-mail. Simply use a string with embedded HTML for ##$mail->body##.
Before sending this out, we have to modify the PHPMailer object to indicate that the message should be interpreted as HTML. Technically-speaking, the message body has to be set up as multipart/alternative. This is done with:
##$mail->IsHTML(true);##
To make ensure that the recipient will be able to read the e-mail, even if his e-mail client doesn't support HTML, use ##$mail->AltBody="Hello, my friend! \n\n## This message uses HTML entities, but you prefer plain text !"; to set the alternative body (AltBody in short). If you use this feature, the mail will be automatically set as multipart/alternative, making it unnecessary to specify ##$mail->IsHTML(true);##.
And that's how to create an HTML email. Simply apply the send command and the mail will be sent. It's recommended that you avoid using HTML messages, because these messages are often used for viruses and exploits, they are much larger than plain text mails, and they're not standardized in the way the plain text mail is. On the other hand, even attachments are used for viruses, but nobody would propose that we stop sending mails with attachments. Do what fits your needs: PHPMailer can be your solution, whatever you decide.
If you want to send out a HTML email with pictures, Flash animations or whatever else, PHPMailer supports this as well.
[Andy Prevost:] Please note that it is not possible to send anything but pure W3C compliant HTML inline with your emails. That means no scripts, no Flash, etc. ... these can be included as attachments, but not as inline viewable objects – other than images (JPG, JPEG, PNG, & GIF). While some email clients may be able to display some objects such as other image types, the vast majority of email clients will either block them, crash, or remove them entirely as inline objects.
Adding an inline picture to your HTML e-mail, for example, is explained in the Inline Attachments section. Briefly, here are 2 lines of code you'd use to insert an image before sending out an e-mail:
##$mail->AddEmbeddedImage("rocks.png", "my-attach", "rocks.png");##
##$mail->Body = 'Embedded Image: <img alt="PHPMailer" src="cid:my-attach"> Here is an image!';##
===Properties===
#|
*| Property (v5.0.0) |Type |Default |Description |*
|| ||
||$Priority |public |3 |Email priority (1 = High, 3 = Normal, 5 = low) ||
||$CharSet |public |iso-8859-1 |Sets the CharSet of the message ||
||$ContentType |public |text/plain |Sets the Content-type of the message ||
||$Encoding |public |8bit |Sets the Encoding of the message. Options for this are "8bit", "7bit", "binary", "base64", and "quoted-printable" ||
||$ErrorInfo |public | |Holds the most recent mailer error message ||
||$From |public |root@localhost |Sets the From email address for the message ||
||$FromName |public | |Root User Sets the From name of the message ||
||$Sender |public | |Sets the Sender email (Return-Path) of the message. If not empty, will be sent via -f to sendmail or as 'MAIL FROM' in smtp mode. ||
||$Subject |public | |Sets the Subject of the message. ||
||$Body |public | |Sets the Body of the message. This can be either an HTML or text body. If HTML then run IsHTML(true). ||
||$AltBody |public | |Sets the text-only body of the message. This automatically sets the email to multipart/alternative. This body can be read by mail clients that do not have HTML email capability such as mutt. Clients that can read HTML will view the normal Body. ||
||$WordWrap |public |0 |Sets word wrapping on the body of the message to a given number of characters ||
||$Mailer |public |mail |Method to send mail: ("mail", "sendmail", or "smtp"). ||
||$Sendmail |public |/usr/sbin/sendmail |Sets the path of the sendmail program. ||
||$PluginDir |public | |Path to PHPMailer plugins. This is now only useful if the SMTP class is in a different directory than the PHP include path. ||
||$ConfirmReadingTo |public | |Sets the email address that a reading confirmation will be sent. ||
||$Hostname |public | |Sets the hostname to use in Message-Id and Received headers and as default HELO string. If empty, the value returned by SERVER_NAME is used or 'localhost.localdomain'. ||
||$Host |public |localhost |Sets the SMTP hosts. All hosts must be separated by a semicolon. You can also specify a different port for each host by using this format: [hostname:port] (e.g. "smtp1.example.com:25;smtp2.example.com"). Hosts will be tried in order. ||
||$Port |public |25 |Sets the default SMTP server port. ||
||$Helo |public | |Sets the SMTP HELO of the message (Default is $Hostname). ||
||$SMTPAuth |public |false |Sets SMTP authentication. Utilizes the Username and Password variables. ||
||$Username |public | |Sets SMTP username. ||
||$Password |public | |Sets SMTP password. ||
||$Timeout |public |10 |Sets the SMTP server timeout in seconds. This function will not work with the win32 version. ||
||$SMTPDebug |public |false |Sets SMTP class debugging on or off. ||
||$SMTPKeepAlive |public |false |Prevents the SMTP connection from being closed after each mail sending. If this is set to true then to close the connection requires an explicit call to SmtpClose(). ||
||$SingleTo |public |false |Provides the ability to have the TO field process individual emails, instead of sending to entire TO addresses ||
|| | | | ||
|#
===Methods===
#|
*| Methods (v5.0.0) |Type |Default |Description |*
|| ||
||set($name, $value) |string $name string $value | |Method provides ability for user to create own custom pseudo-properties (like X-Headers, for example). Example use:
$mail->set('X-MSMail-Priority', 'Normal'); ||
||addCustomHeader($value) |string $value | |Method provides ability for user to create own custom headers (like X-Priority, for example). Example use:
$mail->addCustomHeader("X-Priority: 3"); ||
||MsgHTML($message) | | |Evaluates the message and returns modifications for inline images and backgrounds. Sets the IsHTML() method to true, initializes AltBody() to either a text version of the message or default text. ||
||IsMail() |boolean |true |Sets Mailer to send message using PHP mail() function. (true, false or blank) ||
||IsSMTP() |boolean | |Sets Mailer to send message using SMTP. If set to true, other options are also available. (true, false or blank) ||
||IsSendmail() |boolean | |Sets Mailer to send message using the Sendmail program. (true, false or blank) ||
||IsQmail() boolean | | |Sets Mailer to send message using the qmail MTA. (true, false or blank) ||
||SetFrom($address, $name = " ") |string $address string $name | |Adds a "From" address. ||
||AddAddress($address, $name = " ") |string $address string $name | |Adds a "To" address. ||
||AddCC($address, $name = " ") |string $address string $name | |Adds a "Cc" address. Note: this function works with the SMTP mailer on win32, not with the "mail" mailer. ||
||AddBCC($address, $name = " ") |string $address string $name | |Adds a "Bcc" address. Note: this function works with the SMTP mailer on win32, not with the "mail" mailer. ||
||AddReplyTo($address, $name = " ") |string $address
string $name | |Adds a "Reply-to" address. ||
||Send() | | |Creates message and assigns Mailer. If the message is not sent successfully then it returns false. Use the ErrorInfo variable to view description of the error. Returns true on success, false on failure. ||
||AddAttachment($path, $name = " ", $encoding = "base64",
$type = "application/octet-stream") |string $path
string $name
string $encoding
string $type | |Adds an attachment from a path on the filesystem. Returns false if the file could not be found or accessed. ||
||AddEmbeddedImage($path, $cid, $name = " ", $encoding = "base64",
$type = "application/octet-stream") |string $path
string $cid
string $name
string $encoding
string $type | |Adds an embedded attachment. This can include images, sounds, and just about any other document. Make sure to set the $type to an image type. For JPEG images use "image/jpeg" and for GIF images use "image/gif". If you use the MsgHTML() method, there is no need to use AddEmbeddedImage() method. ||
||ClearAddresses() | | |Clears all recipients assigned in the TO array. Returns void. ||
||ClearCCs() | | |Clears all recipients assigned in the CC array. Returns void. ||
||ClearBCCs() | | |Clears all recipients assigned in the BCC array. Returns void. ||
||ClearReplyTos() | | |Clears all recipients assigned in the ReplyTo array. Returns void. ||
||ClearAllRecipients() | | |Clears all recipients assigned in the TO, CC and BCC array. Returns void. ||
||ClearAttachments() | | |Clears all previously set filesystem, string, and binary attachments. Returns void. ||
||ClearCustomHeaders() | | |Clears all custom headers. Returns void. ||
|#
===Support - Where do I get help?===
PHPMailer is open source and published under the GPL. Most of the questions how to start are answered within this tutorial, but inevitably some questions may well remain. For this, PHPMailer has its own homepage on SourceForge and a mailing list where you can post your questions.
* PHPMailer Homepage: https://github.com/PHPMailer/PHPMailer
* Troubleshooting: https://github.com/PHPMailer/PHPMailer/wiki/Troubleshooting