README

Overview

Maatify Channel Delivery is a standalone async multi-channel delivery microservice for sending notifications across channels like Email, Telegram, SMS, and Push.

It offloads delivery processing from your core applications, ensuring:

• High availability
• Background delivery processing
• Retry mechanisms
• Secure payload encryption
• Controlled API ingestion

Currently, the Email channel is fully implemented and production-ready. Additional channels such as SMS, Telegram, and Push notifications are planned for future releases.

Features

• Async Multi-Channel Queue Process notifications asynchronously using background workers.

• Encrypted Payloads Built-in AES-256-GCM encryption for recipients and message contexts via maatify/crypto.

• Template Rendering Uses Twig to render dynamic email templates safely.

• Reply-To Support Optional reply_to field for admin notification emails — email goes to the admin, replies go to the customer.

• Robust Delivery Exponential retry strategy for transient delivery failures.

• API Key & IP Whitelisting Secure ingestion endpoints allowing only trusted origin servers.

• Rate Limiting Redis-backed sliding window rate limiter to prevent abuse.

• Containerized Dependency Injection Built on Slim 4 + PHP-DI for modular and testable architecture.

Architecture

The system operates as an API ingestion layer combined with background workers.

Applications enqueue notification jobs via HTTP. Workers then process the queue and deliver messages asynchronously.

The email delivery pipeline is powered internally by the maatify/email-delivery library, which provides the rendering, transport abstraction, and delivery engine.

Email Delivery Pipeline

Client Application
↓
Channel Delivery API
↓
Encrypted Queue (Database)
↓
Worker
↓
SMTP Transport
↓
Recipient

Detailed processing steps:

1. Enqueue Client calls /api/v1/email/enqueue.

2. Encryption EnqueueEmailHandler encrypts recipient and context via Maatify\Crypto.

3. Persistence Job stored securely in cd_email_queue.

4. Worker Polling EmailQueueWorker polls pending jobs.

5. Template Rendering Context is decrypted and injected into Twig templates.

6. SMTP Delivery Email is sent via SmtpEmailTransport. If replyTo was set, a Reply-To header is added so replies go to the specified address.

Requirements

• PHP 8.2+
• MySQL / MariaDB
• Redis
• SMTP server
• Composer

Related Projects

• maatify/email-delivery – email delivery engine
• maatify/crypto – encryption layer

Installation

Clone the repository or install via Composer:

composer create-project maatify/channel-delivery
cd channel-delivery

Install dependencies:

composer install --optimize-autoloader --no-dev

Configuration

Create the environment configuration file:

cp .env.example .env

Edit .env and configure the following variables.

Application

Database

Example:

DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=channel_delivery
DB_USERNAME=root
DB_PASSWORD=secret

Encryption (Crypto)

Queue payloads and sensitive data are encrypted using AES-256-GCM through maatify/crypto.

Example:

CRYPTO_ACTIVE_KEY_ID=v1
CRYPTO_KEYS='[{"id":"v1","key":"replace_with_32_byte_secret_here"}]'

Key requirements:

• Key must be exactly 32 bytes
• Keys support rotation
• Old keys remain for decryption only

Generate a secure 32-byte key:

php -r "echo bin2hex(random_bytes(16));"

This will generate a 32-character string, for example:

a3f9c2d1e4b5f6a7c8d9e0f1a2b3c4d5

Then place it inside the .env configuration:

CRYPTO_ACTIVE_KEY_ID=v1
CRYPTO_KEYS='[{"id":"v1","key":"a3f9c2d1e4b5f6a7c8d9e0f1a2b3c4d5"}]'

Key requirements:

• Must be exactly 32 characters
• Used as the symmetric encryption key for AES-256-GCM
• Keys support rotation

SMTP

SMTP configuration used by the email delivery worker.

Redis

Redis is used for rate limiting.

Example:

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_SECONDS=60

Quick Examples

Customer-facing email

Enqueue a transactional email (e.g., welcome, OTP, verification) sent to the customer:

curl -X POST http://localhost:8080/api/v1/email/enqueue \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_generated_api_key" \
  -d '{
    "entity_type": "user",
    "recipient": "user@example.com",
    "template_key": "welcome",
    "language": "en",
    "sender_type": 1,
    "context": {
      "user_name": "Ahmed",
      "activation_link": "https://example.com/activate?token=abc"
    }
  }'

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

Enqueue an admin notification where the email goes to the admin, and replies go to the customer:

curl -X POST http://localhost:8080/api/v1/email/enqueue \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_generated_api_key" \
  -d '{
    "entity_type": "contact_form",
    "recipient": "admin@example.com",
    "reply_to": "customer@example.com",
    "template_key": "admin_notification",
    "language": "en",
    "sender_type": 1,
    "context": {
      "customer_name": "Ahmed",
      "customer_email": "customer@example.com",
      "customer_message": "I need help with my account."
    }
  }'

Worker Usage

Run the email worker:

php scripts/email_worker.php --batch=50 --loop --sleep=5

This worker should normally run under a process manager like Supervisor or systemd.

See the worker setup guide:

Run Worker Guide

Documentation

• Run Worker Guide
• Send Email Guide
• API Documentation: Email Enqueue
• Basic Usage Example

License

This project is open-sourced software licensed under the MIT License.

See the LICENSE file for details.