Introduction
Integrating an SMTP library into your application requires expertise in PHP programming. If you are unsure how to integrate the example script in this tutorial into your PHP application, you must reach out to a PHP developer with the skills and training required to do so for you.
If your application needs to send emails, you have two main options:
- Use PHP's
mail()
function - Use an SMTP library
mail()
function is that it is incredibly simple and easy to use.Although, there are a few downsides to using the
mail()
function:- Microsoft based email providers mark messages created with PHP
mail()
as spam because they do not recognize the DKIM headers that are generated by PHP'smail()
. - The
mail()
function operates in a synchronous manner, forcing the application to wait for the SMTP transaction to complete before being able to do anything else.
When using an SMTP library such as PHPMailer, you won't experience the same drawbacks, but it does require a little bit more setup.
Procedure
This tutorial aims to make the process of setting up the PHPMailer library a very quick and simple task.Command Line Method (Recommended)
NOTE: Please replace cpanelusername with the username of your cPanel user, and replace domain.tld with your domain name.
- Login via Terminal or SSH as the cPanel user
- Navigate to the subdirectory where the script should exist:
Bash:$ mkdir /home/cpanelusername/PHPMailerTest$ cd /home/cpanelusername/PHPMailerTest
- Clone the PHPMailer Library into place with the
git clone
command:
$ git clone https://github.com/PHPMailer/PHPMailer
Cloning into 'PHPMailer'...
remote: Enumerating objects: 37, done.
remote: Counting objects: 100% (37/37), done.
remote: Compressing objects: 100% (26/26), done.
remote: Total 6846 (delta 18), reused 25 (delta 11), pack-reused 6809
Receiving objects: 100% (6846/6846), 4.79 MiB | 6.68 MiB/s, done.
Resolving deltas: 100% (4438/4438), done. - Review the documentation here: PHPMailer Documentation on Github
- Create the script by copying the example script provided later in this guide into the following file:
/home/cpanelusername/PHPMailerTest/testScript.php
- Update the script with your own customizations.
- Test the script with the following command:
$ php /home/cpanelusername/PHPMailerTest/testScript.php
File Manager Method
Although the command line method is recommended, you can use this method if your hosting provider does not provide access to SSH or the Terminal icon.
NOTE: This method requires that you put the script in a publicly accessible location on the server. This can pose a security risk and is only recommended if the file is protected by something like the Directory Privacy feature. This would only be used during testing. After testing is complete you would move your mailer script to a protected location and then call it from your PHP application. Please reach out to a PHP developer if you are unsure about how to call the script from your PHP application.
NOTE: This method requires that you put the script in a publicly accessible location on the server. This can pose a security risk and is only recommended if the file is protected by something like the Directory Privacy feature. This would only be used during testing. After testing is complete you would move your mailer script to a protected location and then call it from your PHP application. Please reach out to a PHP developer if you are unsure about how to call the script from your PHP application.
- Login to the cPanel account for your user.
- Setup Directory Privacy for your "public_html" folder.
- Under the Files section, look for the "File Manager" icon.
- Click on the "public_html" directory to open it.
- Download the PHPMailer library as a zip file: PHPMailer on Github
- Upload the zip file into the FileManager with the "Upload" button from the horizontal menu near the top.
- Use the "Extract" button in the horizontal menu of the File Manager to extract the PHPMailer library.
- Create a new PHP file called "test.php" in the "public_html" directory with the contents of the example script below.
- Update the script with your own customizations.
- Test the script by visiting the URL to the file: https://domain.tld/test.php
Example Script
cPanel Technical Support does not provide assistance with the implementation, debugging, or maintenance of the script in this tutorial. if you encounter errors with your script, please take a look at our How to debug PHPMailer if you see "SMTP Error: Could not authenticate." page for further assistance.
The following Example script is a good place to get started. It is compatible with PHPMailer 6.1.2.This example script uses require statements to the three PHP files that PHPMailer needs to function in the most basic manner.
This script is set up to produce detailed debug output by default. The script requires modification in order to work on your specific environment. You must update the following:
- The paths to the PHP files in the require statements
$mail->Host
- Use your cPanel server's hostname. Your domain name can be used in some cases as well.$mail->Username
- Use the email address of a valid email account on your cPanel server.$mail->Password
- Use the password for the valid email account on your cPanel server.$mail->setFrom
- Use the same address from the Username configuration above.$mail->addAddress
- Set this to the recipient address.$mail->addReplyTo
- Set this to the same address from the Username configuration above.$mail->addCC
- Remove this or set it to a CC recipient address.$mail->addBCC
- Remove this or set it to a BCC recipient address.$mail->addAttachment
- Remove this or update the path to a file to attach.$mail->Subject
- Update this to your desired subject.$mail->Body
- Update this to your desired HTML content. This does not have to be HTML but it can contain HTML.$mail->AltBody
- Update this to a plain text version of your content/message.
Code:
<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;
require '/home/cpanelusername/PHPMailerTest/PHPMailer/src/Exception.php';
require '/home/cpanelusername/PHPMailerTest/PHPMailer/src/PHPMailer.php';
require '/home/cpanelusername/PHPMailerTest/PHPMailer/src/SMTP.php';
// Instantiation and passing [ICODE]true[/ICODE] enables exceptions
$mail = new PHPMailer(true);
try {
//Server settings
$mail->SMTPDebug = 2; // Enable verbose debug output
$mail->isSMTP(); // Set mailer to use SMTP
$mail->Host = 'smtp1.example.com;smtp2.example.com'; // Specify main and backup SMTP servers
$mail->SMTPAuth = true; // Enable SMTP authentication
$mail->Username = 'user@example.com'; // SMTP username
$mail->Password = 'secret'; // SMTP password
$mail->SMTPSecure = 'tls'; // Enable TLS encryption, [ICODE]ssl[/ICODE] also accepted
$mail->Port = 587; // TCP port to connect to
//Recipients
$mail->setFrom('from@example.com', 'Mailer');
$mail->addAddress('recipient1@example.net', 'Joe User'); // Add a recipient
$mail->addAddress('recipient2@example.com'); // Name is optional
$mail->addReplyTo('info@example.com', 'Information');
$mail->addCC('cc@example.com');
$mail->addBCC('bcc@example.com');
// Attachments
$mail->addAttachment('/home/cpanelusername/attachment.txt'); // Add attachments
$mail->addAttachment('/home/cpanelusername/image.jpg', 'new.jpg'); // Optional name
// Content
$mail->isHTML(true); // Set email format to HTML
$mail->Subject = 'Here is the subject';
$mail->Body = 'This is the HTML message body <b>in bold!</b>';
$mail->AltBody = 'This is the body in plain text for non-HTML mail clients';
$mail->send();
echo 'Message has been sent';
} catch (Exception $e) {
echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}