Repository navigation
Releases
v1.2.0 — Durable acceptance and isolated no-send recording
Maatify Email Delivery 1.2.0
Overview
This additive minor release introduces durable keyed enqueue and isolated synthetic no-send recording,
while retaining legacy per-call enqueue and PHP ^8.2 compatibility. PHP 8.2/8.3/8.4/8.5 are covered by CI.
Added
- Explicit namespace/key atomic acceptance with content-conflict detection, encrypted canonical digest,
immutable job/receipt binding and scoped lookup. Durable receipts survive queue deletion and ID reuse. - Optional encrypted synthetic recording in an independent table/domain, with consumer-selected retention
and bounded trusted cleanup. No synthetic record enters the mail worker. - Complete consumer Package Reference, Usage Guide, public-API examples and distribution verification.
Fixed
Receipt-bound worker due/retry decisions and sent timestamps use database UTC even when worker/PHP
sessions are local. Legacy NULL-token/pre-binding rows retain their previous clock behavior.
Compatibility and upgrade
Existing enqueue(): void keeps one insertion per call. Apply the documented fresh or existing-schema
path before keyed adoption; do not run every numbered SQL file indiscriminately. Upgrade every worker
before enabling keyed callers, configure a dedicated idle UTC/autocommit/exception connection, and
retain real receipts/fingerprint read keys indefinitely. Synthetic schema 004 is independent and optional.
Queue acceptance is not exactly-once SMTP or mailbox delivery. Automatic interrupted-processing recovery
and HTTP/timing-equivalence guarantees are not added. Applications own SMTP policy, authorization,
supervision and synthetic cleanup scheduling. See schema upgrade,
keyed contract and synthetic contract.
Release verification
Qualified source: 8e0fc1e2995fb52d1e0e5e299eea2203ccd56c2d.
Full Applicable CI and Release Artifact Verification both passed on this exact main SHA before tagging.
Published artifact verification
Exact maatify/email-delivery:1.2.0 was installed from Packagist in an isolated external Composer project. Observed installation mode: dist. Both distribution references and all 98 installed files matched qualified commit 8e0fc1e2995fb52d1e0e5e299eea2203ccd56c2d.
v1.1.1 – Dynamic Subject Rendering Fix
Maatify Email Delivery v1.1.1
This patch release fixes dynamic email subject rendering when Twig subject blocks contain special characters.
Previously, dynamic subject values were returned with Twig's HTML entities still encoded, causing characters such as &, <, >, and quotes to appear incorrectly in the SMTP subject.
Fixed
- Decode Twig HTML entities from rendered subject blocks before exposing them as the email subject.
- Preserve literal dynamic subject values such as
A & B <Test> "quoted". - Keep normal Twig HTML escaping unchanged for rendered email bodies.
- Added regression coverage verifying both literal SMTP subjects and escaped HTML output.
Backward Compatibility
This release is backward compatible.
- No public API or interface signatures were changed.
- Existing static subject templates continue to work normally.
- Existing HTML body escaping behavior remains unchanged.
Installation
composer require maatify/email-delivery:^1.1Existing installations using ^1.1 can update normally to v1.1.1.
v1.1.0 – Reply-To Support
تمام يا Mohamed — دي مناسبة كـ GitHub Release لـ v1.1.0:
Maatify Email Delivery v1.1.0
This release adds Reply-To support to the Maatify Email Delivery pipeline.
It allows queued emails to define an optional Reply-To address, making it especially useful for admin notifications, contact forms, support messages, and customer-originated emails where replies should go back to the original sender.
✨ Added
- Added optional
replyTosupport toEmailQueuePayloadDTO. - Added optional
$replyToEmailparameter toEmailTransportInterface::send(). - Added Reply-To header handling in
SmtpEmailTransportusing PHPMailer'saddReplyTo(). - Updated
EmailQueueWorkerto extractreplyTofrom the decoded queue payload and pass it to the transport.
🔁 Changed
EmailQueuePayloadDTO::toArray()now includes areplyTokey.- Existing queued payloads without
replyToremain fully backward compatible.
🧩 Use Case
A common use case is admin notification emails:
- Email is sent to the admin
- Reply-To is set to the customer email
- When the admin clicks reply, the response goes directly to the customer
✅ Backward Compatibility
This release is backward compatible.
Existing queue payloads without replyTo continue to work normally.
📦 Installation
composer require maatify/email-delivery:^1.1🧩 Part of the Maatify Ecosystem
This package integrates with:
maatify/crypto
License
MIT License
v1.0.0 – Initial Release
Maatify Email Delivery v1.0.0
Initial public release of the Maatify Email Delivery library.
This package provides a framework-agnostic asynchronous email delivery pipeline for PHP applications.
✨ Features
- Async transactional email queue
- Twig-based email rendering
- SMTP transport via PHPMailer
- Background worker processing
- Encrypted queue payloads using
maatify/crypto - Retry mechanism with backoff strategies
- Batch processing support
- Scheduled email delivery
- Framework-agnostic architecture
🧱 Architecture
The email pipeline is built around four core components:
-
Queue Writer
Encrypts and stores email jobs in the database queue. -
Renderer
Renders Twig email templates with payload data. -
Worker
Processes queued jobs, handles retries, and manages delivery lifecycle. -
SMTP Transport
Sends emails using PHPMailer.
🔐 Security
Sensitive data stored in the queue is encrypted using the maatify/crypto library:
- recipient email encryption
- payload encryption
- key rotation support
This ensures queue data remains protected even if the database is compromised.
🧪 Testing
The library includes a full PHPUnit test suite:
- Unit tests for DTOs, renderer, and queue writer
- Integration tests for the worker pipeline
- Retry mechanism validation
- Encryption round-trip validation
- SQLite in-memory test database
23 tests, 132 assertions
All tests pass through the CI pipeline.
📚 Documentation
Full documentation is available in the repository:
- Book documentation →
docs/book - Guides →
docs/how-to - Examples →
docs/examples
📦 Installation
composer require maatify/email-delivery🧩 Part of the Maatify Ecosystem
This package integrates with:
maatify/crypto
License
MIT License