cPanelResources

Tutorial How to use the PHPMailer library to send messages via SMTP

Warnings
  • Integrating an SMTP library into your application requires expertise in PHP programming. If you are unsure about 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.
  • cPanel Technical Support does not provide assistance with the implementation, debugging, or maintenance of the script in this tutorial.
Introduction

If your application needs to send email, you have two main options:
  1. Use PHP's mail() function
  2. Use an SMTP library

The advantage of using PHP's mail() function is that it is incredibly simple and easy to use.

Although, there are a few downsides to using the mail() function:
1. 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's mail().
2. 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.

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.
  1. Login via Terminal or SSH as the cPanel user
  2. Navigate to the subdirectory where the script should exist:
    Bash:
    $ mkdir /home/cpanelusername/PHPMailerTest$ cd /home/cpanelusername/PHPMailerTest
  3. Clone the PHPMailer Library into place with the git clone command:
    Bash:
    $ git clone https://github.com/PHPMailer/PHPMailerCloning 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.
  4. Review the documentation here: PHPMailer Documentation on Github
  5. Create the script by copying the example script provided later in this guide into the following file:
    /home/cpanelusername/PHPMailerTest/testScript.php
  6. Update the script with your own customizations.
  7. Test the script with the following command:
    Bash:
    $ 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 publically 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.

  1. Login to the cPanel account for your user
  2. Setup Directory Privacy for your public_html folder.
  3. Under the Files section, look for the File Manager icon
  4. Click on the public_html directory to open it
  5. Download the PHPMailer library as a zip file: PHPMailer on Github
  6. Upload the zip file into the FileManager with the Upload button from the horizontal menu near the top
  7. Use the Extract button in the horizontal menu of the File Manager to extract the PHPMailer library
  8. Create a new PHP file called test.php in the public_html directory with the contents of the example script below.
  9. Update the script with your own customizations.
  10. Test the script by visiting the URL to the file: https://domain.tld/test.php

Example Script
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 setup to produce detailed debug output by default.
The script requires modification in order to work on your specific environment. You must update the following:

  1. The paths to the PHP files in the require statements
  2. $mail->Host - Use your cPanel server's hostname. Your domain name can be used in some cases as well.
  3. $mail->Username - Use the email address of a valid email account on your cPanel server.
  4. $mail->Password - Use the password for the valid email account on your cPanel server.
  5. $mail->setFrom - Use the same address from the Username configuration above.
  6. $mail->addAddress - Set this to the recipient address.
  7. $mail->addReplyTo - Set this to the same address from the Username configuration above.
  8. $mail->addCC - Remove this or set it to a CC recipient address.
  9. $mail->addBCC - Remove this or set it to a BCC recipient address.
  10. $mail->addAttachment - Remove this or update the path to a file to attach.
  11. $mail->Subject - Update this to your desired subject.
  12. $mail->Body - Update this to your desired HTML content. This does not have to be HTML but it can contain HTML.
  13. $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   = '[email protected]';                     // 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('[email protected]', 'Mailer');
    $mail->addAddress('[email protected]', 'Joe User');     // Add a recipient
    $mail->addAddress('[email protected]');               // Name is optional
    $mail->addReplyTo('[email protected]', 'Information');
    $mail->addCC('[email protected]');
    $mail->addBCC('[email protected]');

    // 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}";
}
Additional Questions / Feedback
Feel free to click on the Discussion tab to let us know if you have any questions or feedback about the information in this tutorial.
Author
cPanelResources
Views
104
First release
Last update