> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lettr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PHPMailer

> Send emails through Lettr using PHPMailer over SMTP in any PHP project, including WordPress, custom apps, and legacy codebases.

Send emails through Lettr using PHPMailer, the popular PHP email library. PHPMailer works in any PHP project — WordPress, custom applications, or legacy codebases.

## Prerequisites

Before you begin, make sure you have:

> [card] [API Key](https://app.lettr.com/api-keys)
>
> Create an API key in the Lettr dashboard

> [card] [Verified Domain](https://docs.lettr.com/learn/domains/sending-domains.md)
>
> Add and verify your sending domain

You'll also need:

* **PHP 8.0+** installed
* **Composer** for package management (or manual installation)

## Installation

Install PHPMailer via Composer:

```bash theme={null}
composer require phpmailer/phpmailer
```

Or download manually from [GitHub](https://github.com/PHPMailer/PHPMailer) and require the files:

```php theme={null}
require 'path/to/PHPMailer/src/Exception.php';
require 'path/to/PHPMailer/src/PHPMailer.php';
require 'path/to/PHPMailer/src/SMTP.php';
```

## Basic Configuration

Here's a complete example showing how to send an email through Lettr with PHPMailer:

```php theme={null}
<?php

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

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->SMTPDebug = SMTP::DEBUG_OFF;                 // Disable debug output
    $mail->isSMTP();                                    // Use SMTP
    $mail->Host       = 'smtp.lettr.com';               // Lettr SMTP server
    $mail->SMTPAuth   = true;                           // Enable authentication
    $mail->Username   = 'lettr';                        // SMTP username
    $mail->Password   = 'lttr_your_api_key_here';       // Your Lettr API key
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS; // Enable TLS encryption
    $mail->Port       = 587;                            // TCP port

    // Recipients
    $mail->setFrom('you@yourdomain.com', 'Your Name');
    $mail->addAddress('recipient@example.com', 'Recipient Name');
    $mail->addReplyTo('reply@yourdomain.com', 'Reply Address');

    // Content
    $mail->isHTML(true);                                // Set email format to HTML
    $mail->Subject = 'Hello from Lettr';
    $mail->Body    = '<h1>Hello!</h1><p>Welcome to <b>Lettr</b>!</p>';
    $mail->AltBody = 'Hello! Welcome to Lettr!';        // Plain text for non-HTML clients

    $mail->send();
    echo 'Message has been sent successfully';
} catch (Exception $e) {
    echo "Message could not be sent. Mailer Error: {$mail->ErrorInfo}";
}
```

> [!WARNING]
>
> Replace `lttr_your_api_key_here` with your actual Lettr API key. Never commit API keys to version control.

## Adding Attachments

Attach files to your emails using `addAttachment()`:

```php theme={null}
// Attach a PDF file
$mail->addAttachment('/path/to/invoice.pdf', 'invoice.pdf');

// Attach an image
$mail->addAttachment('/path/to/logo.png', 'company-logo.png');

// Attach multiple files
$mail->addAttachment('/path/to/file1.pdf');
$mail->addAttachment('/path/to/file2.docx');
```

The first parameter is the file path, the second (optional) is the filename shown to recipients.

## Adding CC and BCC

Send copies to multiple recipients:

```php theme={null}
// CC (carbon copy) - visible to all recipients
$mail->addCC('manager@example.com');
$mail->addCC('team@example.com', 'Team Lead');

// BCC (blind carbon copy) - hidden from other recipients
$mail->addBCC('bcc@example.com');
$mail->addBCC('archive@example.com');

// Multiple primary recipients
$mail->addAddress('user1@example.com');
$mail->addAddress('user2@example.com');
```

## Open and Click Tracking

Open and click tracking are enabled by default. Add these headers before calling `$mail->send()` to disable both for a message:

```php theme={null}
$mail->addCustomHeader('X-Lettr-Track-Opens', 'false');
$mail->addCustomHeader('X-Lettr-Track-Clicks', 'false');
```

Use the strings `'true'` or `'false'`, and add each header only once. Omitting either header leaves that tracking setting enabled by default. If you reuse a PHPMailer instance, clear its custom headers with `$mail->clearCustomHeaders()` before configuring the next message's headers.

See [SMTP tracking headers](https://docs.lettr.com/learn/sending/tracking.md#smtp-tracking-headers) for validation rules. These are Lettr control headers; arbitrary metadata headers and `X-MSYS-API` are not supported.

## WordPress Integration

If you're using PHPMailer in WordPress, hook into `phpmailer_init`:

```php theme={null}
add_action('phpmailer_init', function($phpmailer) {
    $phpmailer->isSMTP();
    $phpmailer->Host       = 'smtp.lettr.com';
    $phpmailer->SMTPAuth   = true;
    $phpmailer->Username   = 'lettr';
    $phpmailer->Password   = 'lttr_your_api_key_here';
    $phpmailer->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
    $phpmailer->Port       = 587;
});
```

Add this to your theme's `functions.php` or a custom plugin.

## Troubleshooting

> [accordion] SMTP Error: Could not authenticate
>
> Check your API key is correct and starts with `lttr_`. Verify the username is exactly `lettr` (lowercase). Ensure your API key hasn't been revoked in the [dashboard](https://app.lettr.com/api-keys).

> [accordion] SMTP Error: Could not connect to SMTP host
>
> Your firewall may be blocking outbound SMTP connections on port 587. Try alternate ports (`465`, `2465`, or `2587`). Verify `smtp.lettr.com` resolves correctly: `nslookup smtp.lettr.com`.

> [accordion] Invalid address error
>
> Check that all email addresses are properly formatted. Ensure the "from" address uses a verified sending domain.

> [accordion] Could not access file (attachments)
>
> Verify attachment file paths are correct and the PHP process has read permissions. Check that files exist using `file_exists()` before attaching.

> [accordion] Enable debug output
>
> Enable SMTP debugging during development:
>
> ```php theme={null}
> $mail->SMTPDebug = SMTP::DEBUG_SERVER;
> ```
>
> Debug levels:
>
> * `SMTP::DEBUG_OFF` (0) — No output (production)
>
> * `SMTP::DEBUG_CLIENT` (1) — Client messages
>
> * `SMTP::DEBUG_SERVER` (2) — Client and server messages (recommended)
>
> * `SMTP::DEBUG_CONNECTION` (3) — Connection status + messages
>
> * `SMTP::DEBUG_LOWLEVEL` (4) — Low-level data output
>
> > [!WARNING]
> >
> > Never enable debug mode in production. It outputs sensitive information including your API key.

> [accordion] Using port 465 instead of 587
>
> If you prefer port 465 with implicit SSL/TLS:
>
> ```php theme={null}
> $mail->SMTPSecure = PHPMailer::ENCRYPTION_SMTPS;
> $mail->Port       = 465;
> ```
>
> Both ports are equally secure. Port 465 establishes an encrypted connection immediately, while port 587 upgrades via STARTTLS.

## What's Next

> [card] [SMTP Introduction](https://docs.lettr.com/quickstart/smtp/introduction.md)
>
> Learn more about Lettr's SMTP service

> [card] [API Reference](https://docs.lettr.com/api-reference/introduction.md)
>
> Use the HTTP API for more features

> [card] [Troubleshooting](https://docs.lettr.com/knowledge-base/troubleshooting/delivery-issues.md)
>
> Fix common delivery issues

> [card] [Best Practices](https://docs.lettr.com/knowledge-base/best-practices/deliverability.md)
>
> Improve email deliverability


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.