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