Complete PHPMailer Guide

What is PHPMailer?

PHPMailer is a full-featured email creation and transfer class for PHP that solves the limitations of PHP's built-in mail() function. First released in 2001, it has become the most widely used PHP library for sending emails with over 20 million monthly downloads from Packagist.

Why Use PHPMailer?

While PHP's mail() function works for basic needs, PHPMailer provides critical advantages for production websites:

Step 1: Install PHPMailer

The recommended way to install PHPMailer is via Composer, PHP's dependency manager:

composer require phpmailer/phpmailer

This creates a vendor directory containing PHPMailer and its dependencies.

Step 2: Include PHPMailer in Your Script

In your PHP file where you want to send emails, include PHPMailer's autoloader:

require 'vendor/autoload.php';

Step 3: Choose Your Mail Transfer Method

PHPMailer supports multiple ways to send emails. The method you choose depends on your server environment and requirements:

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->isSMTP();
    $mail->Host       = 'smtp.example.com';
    $mail->SMTPAuth   = true;
    $mail->Username   = 'your@email.com';
    $mail->Password   = 'yourpassword';
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
    $mail->Port       = 587;

    // Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('recipient@example.com', 'Joe User');
    
    // Content
    $mail->isHTML(true);
    $mail->Subject = 'SMTP Test Email';
    $mail->Body    = 'This is a test email sent via SMTP';
    
    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Error: {$mail->ErrorInfo}";
}

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->isSendmail();
    // Optional: Specify custom sendmail path
    // $mail->Sendmail = '/usr/sbin/sendmail';
    
    // Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('recipient@example.com', 'Joe User');
    
    // Content
    $mail->isHTML(true);
    $mail->Subject = 'Sendmail Test Email';
    $mail->Body    = 'This is a test email sent via Sendmail';
    
    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Error: {$mail->ErrorInfo}";
}

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->isQmail();
    // Typically Qmail uses this sendmail wrapper:
    $mail->Sendmail = '/var/qmail/bin/sendmail';
    
    // Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('recipient@example.com', 'Joe User');
    
    // Content
    $mail->isHTML(true);
    $mail->Subject = 'Qmail Test Email';
    $mail->Body    = 'This is a test email sent via Qmail';
    
    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Error: {$mail->ErrorInfo}";
}

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->isMail();
    // You may need to configure these in php.ini:
    // sendmail_path = /usr/sbin/sendmail -t -i
    // mail.add_x_header = On
    
    // Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('recipient@example.com', 'Joe User');
    
    // Content
    $mail->isHTML(true);
    $mail->Subject = 'PHP mail() Test Email';
    $mail->Body    = 'This is a test email sent via PHP mail()';
    
    $mail->send();
    echo 'Message has been sent';
} catch (Exception $e) {
    echo "Message could not be sent. Error: {$mail->ErrorInfo}";
}

Security Considerations

Regardless of which sending method you choose, these security practices are essential:

For All Methods:

• Never store credentials in code: Use environment variables or secure configuration files
• Validate all user input: Prevent email header injection attacks
• Use secure connections: When available (especially for SMTP)

Method-Specific Security:

Step 4: Sending Emails (Common to All Methods)

After configuring your transfer method, the email sending process is the same across all methods:

use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\Exception;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings (configured in previous step)
    // $mail->isSMTP(); or $mail->isSendmail(); etc.
    
    // Recipients
    $mail->setFrom('from@example.com', 'Mailer');
    $mail->addAddress('recipient@example.com', 'Joe User');
    $mail->addReplyTo('info@example.com', 'Information');
    
    // Content
    $mail->isHTML(true);
    $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. Error: {$mail->ErrorInfo}";
}

Working with Attachments

PHPMailer makes it easy to add attachments regardless of your transfer method:

// Add a simple attachment
$mail->addAttachment('/path/to/file.pdf');

// Add attachment with custom filename
$mail->addAttachment('/path/to/image.jpg', 'photo.jpg');

// Add embedded image (works in HTML body)
$mail->addEmbeddedImage('/path/to/logo.png', 'logo');
// Then in HTML body: <img src="cid:logo">

HTML Email Templates

Create professional HTML emails with PHPMailer:

$mail->isHTML(true);
$mail->Subject = 'Your Subject Here';

$htmlContent = '
<!DOCTYPE html>
<html>
<head>
    <title>Email Template</title>
    <style>
        body { font-family: Arial, sans-serif; }
        .container { max-width: 600px; margin: 0 auto; }
        .header { background-color: #4361ee; color: white; padding: 20px; }
        .content { padding: 20px; }
        .footer { background-color: #f8f9fa; padding: 10px; text-align: center; }
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>Hello, {name}!</h1>
        </div>
        <div class="content">
            <p>This is a sample HTML email template.</p>
            <p>You can customize it with your own content.</p>
        </div>
        <div class="footer">
            <p>© 2023 Your Company</p>
        </div>
    </div>
</body>
</html>
';

// Replace placeholders with actual values
$htmlContent = str_replace('{name}', 'John Doe', $htmlContent);

$mail->Body = $htmlContent;
$mail->AltBody = 'Hello John Doe,\n\nThis is a sample HTML email template.\n\nYou can customize it with your own content.\n\n© 2023 Your Company';

Testing & Troubleshooting

After implementation, test your email functionality thoroughly:

Testing Checklist

• Verify emails arrive in the inbox (not spam)
• Test with both HTML and plain text clients
• Check attachment delivery
• Verify sender information displays correctly

Debugging Tips

// Enable verbose debug output
$mail->SMTPDebug = 2; // 1 = errors/messages, 2 = messages only

// Or for non-SMTP methods
$mail->Debugoutput = function($str, $level) {
    file_put_contents('mail.log', "$level: $str\n", FILE_APPEND);
};

Best Practices

Follow these guidelines for optimal email delivery and maintainability:

General Best Practices

• Always use exception handling (try/catch)
• Implement proper error logging
• Use environment variables for sensitive data
• Keep your PHPMailer version updated

Performance Tips

• Reuse PHPMailer instances when sending multiple emails
• For bulk emails, consider queueing systems
• Optimize HTML email size (keep under 100KB)