Download the PHP package lettr/lettr-php without Composer
On this page you can find all versions of the php package lettr/lettr-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package lettr-php
Lettr PHP SDK
Official PHP SDK for the Lettr email API.
Requirements
- PHP 8.4+
- Guzzle HTTP client 7.5+ or 8.x
Installation
Quick Start
Sending Emails
Using the Email Builder (Recommended)
The fluent builder provides a clean API for constructing emails:
Using SendEmailData DTO
For programmatic email construction:
Quick Send Methods
For simple use cases:
The from parameter accepts a plain email string or an EmailAddress value object when you need a sender name:
Attachments
Templates with Substitution Data
Custom Headers
You can add custom email headers (e.g. X-Custom-ID, X-Entity-Ref-ID) to your emails. Maximum 10 headers, each value up to 998 characters:
Note: Some standard headers (e.g.
List-Unsubscribefor non-transactional emails) may be overwritten by the email delivery provider. Use custom headers for application-specific headers likeX-Custom-ID.
Email Options
Emails are sent as transactional by default, matching the API's default behavior. For marketing emails, explicitly set transactional(false):
Idempotent Sends
Attach an Idempotency-Key and a retry of the same send returns the original
result instead of delivering a second email:
You choose the key; the SDK never generates one. It only works if the same
key is used on both attempts, and the SDK does not retry — one send() is one
HTTP request — so the retry is yours. Use something stable for one logical send:
an order id, a job id, anything you can regenerate. A fresh value per attempt
protects nothing.
If you have no natural id, IdempotencyKey::forPayload($data) derives one from
the payload. Note the trade: two deliberately identical sends within 24 hours
then collapse into one.
Handle the two conflicts differently — one is retryable and the other is not:
Both extend ConflictException, so existing handlers keep catching them.
| Format | 1–255 characters, [A-Za-z0-9._-] — validated locally before the request |
| Retention | 24 hours |
| Scope | Per team and API key — the same string through a different API key is a different key |
Scheduled Emails
Schedule an email for any time between 5 minutes and 30 days out. Lettr holds it until then, so it can be listed, read back and cancelled right up to the moment it is sent.
The two ids are not interchangeable. requestId identifies the scheduled email for its whole life. transmissionId is the sending provider's id: it stays null until the email goes out, and it is the value that appears on your webhook events, so use that one to correlate them.
States are Scheduled, Sending, Sent, Cancelled and Failed. Cancelling is only possible while Scheduled; once it is being sent or has been sent, cancelScheduled() throws a ConflictException. A Failed email carries a failureReason.
Once an email has been sent, events fills in from its delivery events — empty before that, and for a few minutes afterwards while they are indexed.
Marketing Emails & Unsubscribe
When sending marketing emails (transactional(false)), the email provider automatically adds List-Unsubscribe and List-Unsubscribe-Post headers for compliance. To allow recipients to unsubscribe from your marketing emails:
- Add an unsubscribe link in your HTML using the
data-msys-unsubscribeattribute:
The href must use https:// — when clicked, the user will be redirected to your URL. The actual unsubscribe handling should be done server-side by listening for webhook events.
- Listen for unsubscribe events via webhooks — subscribe to
link_unsubscribeandlist_unsubscribeevent types to process unsubscribes in your application.
Health Check
Value Objects
The SDK uses value objects for type safety and validation:
Error Handling
Rate Limits
The API enforces a rate limit of 3 requests per second per team, shared across all API keys. Rate limit headers are included in every authenticated API response:
| Header | Description |
|---|---|
X-Ratelimit-Limit |
Maximum requests per second |
X-Ratelimit-Remaining |
Remaining requests in current window |
X-Ratelimit-Reset |
Unix timestamp when the limit resets |
Retry-After |
Seconds to wait (only on 429 responses) |
You can read rate limit info after any API call:
Sending Quotas
Free tier teams have monthly and daily sending limits. Quota headers are included in send email responses:
| Header | Description |
|---|---|
X-Monthly-Limit |
Total monthly email limit |
X-Monthly-Remaining |
Remaining emails this month |
X-Monthly-Reset |
Unix timestamp when monthly quota resets |
X-Daily-Limit |
Total daily email limit |
X-Daily-Remaining |
Remaining emails today |
X-Daily-Reset |
Unix timestamp when daily quota resets |
Quota information is available on successful responses via $response->quota and on quota exceeded errors via the QuotaExceededException.
Documentation
Full guides, every method, and complete request/response details live in the docs:
📚 docs.lettr.com/quickstart/php
| Topic | Guide |
|---|---|
| Install & client setup | Installation |
| Sending — HTML, text, templates, attachments, tracking, errors | Sending Emails |
| Managing templates & merge tags | Templates |
| Add, verify, and manage sending domains | Domains |
| Webhook endpoints for delivery & engagement events | Webhooks |
| Lists, contacts, topics, properties, segments | Audience |
| List, send, and schedule campaigns | Campaigns |
| Endpoint reference (params & schemas) | API Reference |
Development
Install Dependencies
Code Style
This project uses Laravel Pint for code style:
Static Analysis
This project uses PHPStan at level 8:
Testing
This project uses Pest for testing:
Contributing
Please see CONTRIBUTING for details.
License
MIT License. See LICENSE for details.