README

Overview

Maatify Email Delivery is a standalone module for rendering, queueing, and sending transactional emails.

It provides:

Async transactional email delivery
Twig email rendering
Queue-based delivery
SMTP transport via PHPMailer
Background worker processing
Encrypted payload storage via maatify/crypto
Framework-agnostic architecture

Why This Library

This library solves several common problems in web applications:

Synchronous email sending blocking requests and slowing down user responses.
Unreliable delivery in high-volume systems when SMTP servers drop connections.
Lack of templating systems for clean, maintainable transactional email layouts.
Difficulty scaling email infrastructure.

By decoupling the process, the library introduces an robust async email pipeline.

Features

Async email queue
Twig template rendering
SMTP transport (PHPMailer)
Background worker processing
Encrypted queue payloads
Retry mechanism for failed emails
Reply-To support — optional Reply-To header for admin notifications ¹
Framework-agnostic design
Designed for transactional email systems

¹ Available since v1.1.0

Quick Examples

Basic usage — customer-facing email

use Maatify\EmailDelivery\Queue\DTO\EmailQueuePayloadDTO;
use Maatify\EmailDelivery\Queue\PdoEmailQueueWriter;

// 1. Initialize Queue Writer
$queueWriter = new PdoEmailQueueWriter($pdo, $cryptoProvider, $cryptoContext);

// 2. Create Payload
$payload = new EmailQueuePayloadDTO(
    templateKey: 'welcome',
    language: 'en',
    context: ['name' => 'John Doe']
);

$email = 'john.doe@example.com';

// 3. Enqueue the email
$queueWriter->enqueue(
    entityType: 'user',
    entityId: '123',
    recipientEmail: $email,
    payload: $payload,
    senderType: 1,
    priority: 10
);

Admin notification with Reply-To (v1.1.0+)

use Maatify\EmailDelivery\Queue\DTO\EmailQueuePayloadDTO;

// Payload with optional replyTo — email goes TO the admin,
// but Reply-To is set to the customer so admin replies reach them.
$payload = new EmailQueuePayloadDTO(
    templateKey: 'admin_notification',
    language: 'en',
    context: [
        'customer_name'    => 'Ahmed',
        'customer_email'   => 'customer@example.com',
        'customer_message' => 'I need help with my account.',
    ],
    replyTo: 'customer@example.com',
);

$queueWriter->enqueue(
    entityType: 'contact_form',
    entityId: '456',
    recipientEmail: 'admin@example.com',
    payload: $payload,
    senderType: 1,
    priority: 5
);

Architecture Overview

The email delivery pipeline relies on four main components:

Renderer: Compiles data and Twig templates into HTML/Text content.
Queue Writer: Securely encrypts and stores the payload in the database queue.
Worker: A background process that decrypts, renders, and attempts delivery.
Transport: The SMTP layer that physically sends the email.

Application
      ↓
Queue Writer
      ↓
Database Queue
      ↓
Email Worker
      ↓
SMTP Transport

Email Delivery Pipeline

Request → Queue → Worker → SMTP → Recipient

This system intentionally decouples email sending from application requests. Your application immediately responds to the user while the background worker handles the potentially slow and error-prone process of rendering and SMTP transmission.

System Diagrams

Architecture

Email Flow

Worker Lifecycle

Installation

composer require maatify/email-delivery

Documentation

Book:

docs/book/README.md

Guides:

docs/how-to/README.md

Examples:

docs/examples/README.md

Ecosystem

This package is part of the Maatify Ecosystem.

It relies on the maatify/crypto dependency to provide robust encryption. Encryption is used specifically for queue payload security, ensuring that sensitive transactional data (like password reset tokens or PII) remains unreadable if the queue database is ever compromised.

License

MIT License

maatify / email-delivery

Maintainers

Package info

Statistics

Security