PHPackages                             maatify/channel-delivery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Caching](/categories/caching)
4. /
5. maatify/channel-delivery

ActiveProject[Caching](/categories/caching)

maatify/channel-delivery
========================

Maatify Channel Delivery — Standalone async multi-channel delivery microservice (Email, Telegram, SMS, Push...)

v1.1.0(1mo ago)00MITPHPPHP ^8.2CI passing

Since Mar 12Pushed 1mo agoCompare

[ Source](https://github.com/Maatify/channel-delivery)[ Packagist](https://packagist.org/packages/maatify/channel-delivery)[ Docs](https://github.com/Maatify/channel-delivery)[ RSS](/packages/maatify-channel-delivery/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (2)Dependencies (36)Versions (4)Used By (0)

Maatify Channel Delivery
========================

[](#maatify-channel-delivery)

[![Latest Version on Packagist](https://camo.githubusercontent.com/797306624746f15efa429971690ae28ad600bceecb704beed006241b27bd9142/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6161746966792f6368616e6e656c2d64656c69766572792e737667)](https://packagist.org/packages/maatify/channel-delivery)

[![PHP Version](https://camo.githubusercontent.com/15bf8390b232eb4a6e5383b41a032b6fd813dbd47dc32b0bb3204befdfef3237/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d6161746966792f6368616e6e656c2d64656c69766572792e737667)](https://packagist.org/packages/maatify/channel-delivery)

[![License](https://camo.githubusercontent.com/05adad3c2c2b6b5210aaa5f432f4620ec8a32a885f5c2f373c2e61494209f44c/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d6161746966792f6368616e6e656c2d64656c69766572792e737667)](LICENSE)

[![CI](https://github.com/Maatify/channel-delivery/actions/workflows/ci.yml/badge.svg)](https://github.com/Maatify/channel-delivery/actions)

[![Maatify Ecosystem](https://camo.githubusercontent.com/e909123cad12b048a0b4441f2b9cfb19aebfb3986afe8e3631da84255281c12d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6161746966792d45636f73797374656d2d626c756576696f6c6574)](https://camo.githubusercontent.com/e909123cad12b048a0b4441f2b9cfb19aebfb3986afe8e3631da84255281c12d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4d6161746966792d45636f73797374656d2d626c756576696f6c6574)

Overview
--------

[](#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
--------

[](#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
------------

[](#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.

[![Architecture Diagram](docs/assets/architecture-diagram.svg)](docs/assets/architecture-diagram.svg)

The email delivery pipeline is powered internally by the [`maatify/email-delivery`](https://github.com/Maatify/email-delivery)library, which provides the rendering, transport abstraction, and delivery engine.

---

Email Delivery Pipeline
-----------------------

[](#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.

[![Email Flow Diagram](docs/assets/email-flow-diagram.svg)](docs/assets/email-flow-diagram.svg)

---

Requirements
------------

[](#requirements)

- PHP **8.2+**
- MySQL / MariaDB
- Redis
- SMTP server
- Composer

---

Related Projects
----------------

[](#related-projects)

- [`maatify/email-delivery`](https://github.com/Maatify/email-delivery) – email delivery engine
- [`maatify/crypto`](https://github.com/Maatify/crypto) – encryption layer

---

Installation
------------

[](#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
-------------

[](#configuration)

Create the environment configuration file:

```
cp .env.example .env
```

Edit `.env` and configure the following variables.

### Application

[](#application)

VariableDescription`APP_ENV`Application environment (`development` / `production`)`APP_NAME`Name of the service instance`SUPPORT_EMAIL`Support contact email---

### Database

[](#database)

VariableDescription`DB_HOST`Database host`DB_PORT`Database port`DB_DATABASE`Database name`DB_USERNAME`Database username`DB_PASSWORD`Database passwordExample:

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

---

### Encryption (Crypto)

[](#encryption-crypto)

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

VariableDescription`CRYPTO_ACTIVE_KEY_ID`Identifier of the active encryption key`CRYPTO_KEYS`JSON array containing encryption keysExample:

```
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)

SMTP configuration used by the email delivery worker.

VariableDescription`MAIL_HOST`SMTP server host`MAIL_PORT`SMTP server port`MAIL_USERNAME`SMTP username`MAIL_PASSWORD`SMTP password`MAIL_FROM_ADDRESS`Default sender email`MAIL_FROM_NAME`Sender display name`MAIL_ENCRYPTION`Encryption type (`tls` / `ssl`)`MAIL_TIMEOUT`SMTP timeout (seconds)`MAIL_DEBUG`SMTP debug mode (0 = disabled)---

### Redis

[](#redis)

Redis is used for **rate limiting**.

VariableDescription`REDIS_HOST`Redis host`REDIS_PORT`Redis port`REDIS_PASSWORD`Redis password (optional)`REDIS_DB`Redis database index`RATE_LIMIT_MAX_REQUESTS`Maximum requests allowed`RATE_LIMIT_WINDOW_SECONDS`Rate limit window duration`TRUSTED_PROXIES`Trusted proxy IPs (for `X-Forwarded-For`)Example:

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

---

Quick Examples
--------------

[](#quick-examples)

### Customer-facing email

[](#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+)

[](#admin-notification-with-reply-to-v110)

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
------------

[](#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](docs/how-to/run-worker.md)

---

Documentation
-------------

[](#documentation)

- [Run Worker Guide](docs/how-to/run-worker.md)
- [Send Email Guide](docs/how-to/send-email.md)
- [API Documentation: Email Enqueue](docs/api/email-enqueue.md)
- [Basic Usage Example](docs/examples/basic-usage.php)

---

License
-------

[](#license)

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

See the [LICENSE](LICENSE) file for details.

###  Health Score

39

—

LowBetter than 85% of packages

Maintenance93

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 94.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~33 days

Total

3

Last Release

37d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1a885a0810f2762586520ab284c9019aaf0b650b53cdf2a6c13ea10931bb7795?d=identicon)[Maatify](/maintainers/Maatify)

---

Top Contributors

[![megyptm](https://avatars.githubusercontent.com/u/33574895?v=4)](https://github.com/megyptm "megyptm (16 commits)")[![Maatify](https://avatars.githubusercontent.com/u/130119162?v=4)](https://github.com/Maatify "Maatify (1 commits)")

---

Tags

asyncbackground-workeremailmaatifymaatify-devmaatify-ecosystemmicroservicenotificationsphpphp-diqueueredisslimsmtpasyncpushemailsmsqueuetelegramdeliveryMicroservicemaatify

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maatify-channel-delivery/health.svg)

```
[![Health](https://phpackages.com/badges/maatify-channel-delivery/health.svg)](https://phpackages.com/packages/maatify-channel-delivery)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[symfony/symfony

The Symfony PHP framework

31.4k86.9M2.2k](/packages/symfony-symfony)[cakephp/cakephp

The CakePHP framework

8.8k19.1M1.7k](/packages/cakephp-cakephp)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[phlak/directory-lister

PHP directory lister

2.5k1.4k](/packages/phlak-directory-lister)[eliashaeussler/typo3-warming

Warming - Warms up Frontend caches based on an XML sitemap. Cache warmup can be triggered via TYPO3 backend or using a console command. Supports multiple languages and custom crawler implementations.

22249.2k](/packages/eliashaeussler-typo3-warming)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)