README

Integrate Lettermint in your PHP project.

Requirements

• PHP 8.2 or higher
• Composer

Installation

You can install the package via composer:

composer require lettermint/lettermint-php

Usage

Initialize the Lettermint client with your Sending API token:

$lettermint = new Lettermint\Lettermint('your-api-token');

For new integrations, prefer explicit clients for the two API surfaces:

$email = Lettermint\Lettermint::email(getenv('LETTERMINT_SENDING_TOKEN'));
$api = Lettermint\Lettermint::api(getenv('LETTERMINT_API_TOKEN'));

Sending API tokens are project-specific and authenticate with the x-lettermint-token header. API tokens are team-scoped and authenticate with Authorization: Bearer .... Keep these tokens separate and never reuse an API token for sending-only workloads.

Sending Emails

The SDK provides a fluent interface for composing and sending emails:

$response = $lettermint->email
                       ->from('sender@example.com')
                       ->to('recipient@example.com')
                       ->subject('Hello from Lettermint!')
                       ->text('Hello! This is a test email.')
                       ->send();

The SDK supports various email features:

$lettermint->email
    ->from('John Doe <john@example.com>')
    ->to('recipient1@example.com', 'recipient2@example.com')
    ->cc('cc@example.com')
    ->bcc('bcc@example.com')
    ->replyTo('reply@example.com')
    ->subject('Hello world!')
    ->html('<h1>Hello!</h1>')
    ->text('Hello!')
    ->headers(['X-Custom-Header' => 'Value'])
    ->attach('document.pdf', base64_encode($fileContent))
    ->attach('logo.png', base64_encode($logoContent), 'logo@example.com')
    ->route('my-route-id')
    ->idempotencyKey('unique-request-id-123')
    ->send();

You can also send with an array payload:

$response = $email->send([
    'from' => 'sender@example.com',
    'to' => ['recipient@example.com'],
    'subject' => 'Hello from Lettermint!',
    'text' => 'Hello! This is a test email.',
]);

Batch Sending

$response = $email->sendBatch([
    [
        'from' => 'sender@example.com',
        'to' => ['recipient@example.com'],
        'subject' => 'First email',
        'text' => 'Hello!',
    ],
    [
        'from' => 'sender@example.com',
        'to' => ['another@example.com'],
        'subject' => 'Second email',
        'text' => 'Hello again!',
    ],
]);

Inline Attachments

You can embed images and other content in your HTML emails using content IDs:

$lettermint->email
    ->from('sender@example.com')
    ->to('recipient@example.com')
    ->subject('Email with inline image')
    ->html('<p>Here is an image: <img src="cid:logo@example.com"></p>')
    ->attach('logo.png', base64_encode($imageContent), 'logo@example.com')
    ->send();

Idempotency

To ensure that duplicate requests are not processed, you can use an idempotency key:

$response = $lettermint->email
                       ->from('sender@example.com')
                       ->to('recipient@example.com')
                       ->subject('Hello from Lettermint!')
                       ->text('Hello! This is a test email.')
                       ->idempotencyKey('unique-request-id-123')
                       ->send();

The idempotency key should be a unique string that you generate for each unique email you want to send. If you make the same request with the same idempotency key, the API will return the same response without sending a duplicate email.

For more information, refer to the documentation.

API Client

Use the API client for team-scoped resources such as projects, domains, routes, suppressions, stats, messages, and webhooks:

$api = Lettermint\Lettermint::api(getenv('LETTERMINT_API_TOKEN'));

$projects = $api->projects->list(['filter[search]' => 'production']);

$project = $api->projects->create([
    'name' => 'Production',
    'smtp_enabled' => false,
]);

$api->domains->verifyDnsRecords('domain-id');

$stats = $api->stats->retrieve([
    'from' => '2026-05-01',
    'to' => '2026-05-09',
]);

$api->suppressions->create([
    'email' => 'user@example.com',
    'reason' => 'manual',
    'scope' => 'team',
]);

$api->webhooks->create([
    'route_id' => 'route-id',
    'name' => 'Production webhook',
    'url' => 'https://example.com/lettermint/webhook',
    'events' => ['message.sent', 'message.delivered'],
]);

Both API surfaces support ping():

$email->ping();
$api->ping();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Upgrading

Please see UPGRADE.md for guidance on upgrading from v1 to v2.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Bjarn Bronsveld
• All Contributors

License

The MIT License (MIT). Please see License File for more information.