PHPackages                             monkeyscloud/monkeyslegion-mail - 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. [Logging & Monitoring](/categories/logging)
4. /
5. monkeyscloud/monkeyslegion-mail

ActiveLibrary[Logging & Monitoring](/categories/logging)

monkeyscloud/monkeyslegion-mail
===============================

Mail integration package for the MonkeysLegion framework.

2.1.2(2w ago)11.9k↓30.4%2MITPHPPHP ^8.4

Since Jul 23Pushed 2w agoCompare

[ Source](https://github.com/MonkeysCloud/MonkeysLegion-Mail)[ Packagist](https://packagist.org/packages/monkeyscloud/monkeyslegion-mail)[ RSS](/packages/monkeyscloud-monkeyslegion-mail/feed)WikiDiscussions main Synced yesterday

READMEChangelog (1)Dependencies (55)Versions (18)Used By (2)

🐒 MonkeysLegion Mail (v2)
=========================

[](#-monkeyslegion-mail-v2)

A premium, high-performance mail engine for the **MonkeysLegion PHP framework**. Features PSR-14 events, DKIM signing, rate limiting, and a beautiful fluent API. Our codebase is rigorously tested with **288 unit and integration tests** ensuring **82.88% code coverage**.

[![PHP Version](https://camo.githubusercontent.com/2aed50cc19486e0407775311c22f530383b2791ca08b8c9583ebb80cb5e364e7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e342532422d626c75652e737667)](https://php.net)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)![Tests](https://camo.githubusercontent.com/2ab9e0d8320ab71289d26aa3ae34fa38243963cd4d59f11267df6700269d147f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f74657374732d3238382532307061737365642d627269676874677265656e2e737667)![Coverage](https://camo.githubusercontent.com/eb9c80604120eda39048f0eb3a28f8ec64ca12b192539c8f5a337e2d481e8dd6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d38322e38382532352d627269676874677265656e2e737667)

---

🚀 Quick Start: From Zero to "Sent"
----------------------------------

[](#-quick-start-from-zero-to-sent)

### 1. Installation

[](#1-installation)

Install the package via composer:

```
composer require monkeyscloud/monkeyslegion-mail:^2.0
```

Initialize the mail configuration and scaffold resources:

```
php ml mail:install
```

### 2. Configuration

[](#2-configuration)

Configure your sending credentials in your `.env` file. By default, the package uses the **Null Driver** for safe development.

```
# Choose your driver (monkeys_mail, smtp, mailgun, sendmail, null)
MAIL_DRIVER=smtp

# SMTP Settings
MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=your_username
MAIL_PASSWORD=your_password

# Global Identity
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Monkeys Legion App"
```

### 3. Manual Construction (DI)

[](#3-manual-construction-di)

If you are not using the full MonkeysLegion framework auto-wiring, here is how to manually construct the `Mailer` and its dependencies:

```
use MonkeysLegion\Mail\Mailer;
use MonkeysLegion\Mail\Transport\SmtpTransport;
use MonkeysLegion\Mail\RateLimiter\RateLimiter;

$transport = new SmtpTransport([
    'host' => 'smtp.example.com',
    'port' => 587,
    'username' => 'user',
    'password' => 'secret'
]);

$rateLimiter = new RateLimiter('my_mail_app', 100, 60);

$mailer = new Mailer(
    $transport,
    $rateLimiter,
    $queueDispatcher, // MonkyesLegion-Queue (optional)
    $logger,          // PSR-3 or MonkeysLogger (optional)
    [],               // Raw configuration array for run time driver selection
    $eventDispatcher  // PSR-14 global dispatcher (optional)
);
```

### 4. Basic Sending (Direct)

[](#4-basic-sending-direct)

Get the `Mailer` instance from the container and send an email immediately:

```
use MonkeysLegion\Mail\Mailer;

// Resolve the mailer
$mailer = $container->get(Mailer::class);

$mailer->send(
    'recipient@example.com',
    'Hello from v2!',
    'Success!The MonkeysLegion mail engine is operational.',
    'text/html'
);
```

### 5. Advanced: Using Mailables

[](#5-advanced-using-mailables)

Generate a new Mailable class:

```
php ml make:mail WelcomeMail
```

Configure your logic and templates in `src/Mail/WelcomeMail.php`:

```
public function build(): self
{
    return $this->view('emails.welcome')
                ->subject('Welcome!')
                ->withData(['name' => $this->user->name]);
}
```

Then send or queue it fluently:

```
(new WelcomeMail($user))
    ->setTo('user@example.com')
    ->send(); // or ->queue() for background processing
```

### With Metadata (Mailables)

[](#with-metadata-mailables)

When using **Mailables** with metadata-aware transports, set metadata in your `build()` method:

```
public function build(): self
{
    return $this->view('emails.welcome')
                ->subject('Welcome!')
                ->withTags(['onboarding', 'transactional'])
                ->withMetadata(['user_id' => $this->user->id, 'source' => 'signup'])
                ->withVariables(['activation_url' => $url, 'name' => $this->user->name])
                ->replyTo('support@example.com');
}
```

---

📨 Advanced Email Metadata (MonkeysMailTransport & MailgunTransport)
-----------------------------------------------------------------------

[](#-advanced-email-metadata-monkeysmailtransport--mailguntransport)

The **MonkeysMailTransport** and **MailgunTransport** support rich email metadata through the `SupportsAdvancedMetadata` interface. This allows you to send tags, custom metadata, template variables, and reply-to addresses. Metadata is preserved when sending via `Mailer` or `Mailable` classes.

### Using Metadata in Mailables

[](#using-metadata-in-mailables)

```
(new WelcomeMail($user))
    ->setTo('user@example.com')
    ->withTags(['onboarding', 'transactional'])                          // Categorization tags
    ->withMetadata(['user_id' => $user->id, 'source' => 'signup'])      // Custom key-value data
    ->withVariables(['activation_url' => $url, 'name' => $user->name])  // Template substitutions
    ->replyTo('support@example.com')                                     // Reply-To address
    ->send();
```

### Using Metadata via Mailer (Direct Messages)

[](#using-metadata-via-mailer-direct-messages)

```
use MonkeysLegion\Mail\Message;

$mailer = $container->get(Mailer::class);

$message = new Message('user@example.com', 'Hello!', 'Welcome');
$message->setTags(['onboarding', 'promotion']);
$message->setMetadata(['campaign_id' => '12345', 'segment' => 'premium']);
$message->setVariables(['first_name' => 'John', 'discount' => '20%']);
$message->setReplyTo('support@example.com');

// Send with metadata preserved
$mailer->sendMessage($message);

// Or queue with metadata preserved
$mailer->queueMessage($message, 'high-priority');
```

### Using Metadata Directly with Message & Transport

[](#using-metadata-directly-with-message--transport)

```
$message = new Message('user@example.com', 'Hello!', 'Welcome');
$message->setTags(['onboarding', 'promotion']);
$message->setMetadata(['campaign_id' => '12345', 'segment' => 'premium']);
$message->setVariables(['first_name' => 'John', 'discount' => '20%']);
$message->setReplyTo('support@example.com');

$transport->send($message);
```

### Metadata Field Details

[](#metadata-field-details)

FieldTypePurposeExample**tags**`array`Categorize emails for tracking/analytics`['onboarding', 'transactional', 'marketing']`**metadata**`array`Custom key-value pairs`['user_id' => 123, 'campaign' => 'summer2025']`**variables**`array`Template variable substitutions`['first_name' => 'John', 'code' => 'ABC123']`**replyTo**`?string`Reply-To email address`'support@example.com'`### Supported Transports

[](#supported-transports)

- ✅ **MonkeysMailTransport** - Full support for all metadata fields
- ❌ **SmtpTransport** - Ignores metadata (standard SMTP limitation)
- ❌ **SendmailTransport** - Ignores metadata
- ✅ **MailgunTransport** - Supports tags (max 3), variables, metadata (v:metadata JSON), reply-to
- ❌ **NullTransport** - Ignores metadata

**Note:** Transports that don't support metadata simply ignore these fields without error. This ensures backward compatibility.

---

🏗️ Transport Interface: SupportsAdvancedMetadata
------------------------------------------------

[](#️-transport-interface-supportsadvancedmetadata)

To add metadata support to a custom transport, implement the marker interface:

```
use MonkeysLegion\Mail\TransportInterface;
use MonkeysLegion\Mail\SupportsAdvancedMetadata;

class MyCustomTransport implements TransportInterface, SupportsAdvancedMetadata
{
    public function send(Message $message): void
    {
        // Extract metadata from the message
        $tags = $message->getTags();           // array
        $metadata = $message->getMetadata();   // array
        $variables = $message->getVariables(); // array
        $replyTo = $message->getReplyTo();     // ?string

        // Use these fields in your API payload or business logic
    }

    public function getName(): string
    {
        return 'my-custom-transport';
    }
}
```

---

🔔 Events & Hooks (New in v2)
--------------------------------

[](#-events--hooks-new-in-v2)

Listen to successful sends or failures globally via PSR-14, or locally on the instances.

```
$mailer->onSent(function ($event) {
    echo "Message " . $event->getMessageId() . " sent successfully!";
});

$mailer->onFailed(function ($event) {
    Log::error("Failed to send: " . $event->getException()->getMessage());
});
```

See the **[Events Documentation](docs/events.md)** for details on the PSR-14 implementation.

---

📖 Complete Documentation
------------------------

[](#-complete-documentation)

Explore each feature in detail:

- **[🚌 Transports & Drivers](docs/transports.md)**: SMTP, MonkeysMail API, Mailgun, and more.
- **[🎨 Mailable Classes](docs/mailables.md)**: Object-oriented composition and data binding.
- **[📊 Queue System](docs/queues.md)**: High-performance background processing.
- **[🛡️ DKIM Signing](docs/dkim.md)**: Ensure deliverability with cryptographic signatures.
- **[🚦 Security & Logging](docs/security.md)**: Rate limiting and monitoring.
- **[🔧 CLI Commands](docs/cli.md)**: Scaffolding and testing tools.

---

✨ Why MonkeysLegion Mail?
-------------------------

[](#-why-monkeyslegion-mail)

- **PSR-14 Native**: Full event-driven architecture.
- **DKIM Built-in**: Modern security standards out-of-the-box.
- **Rate Limited**: Protect your reputation and costs automatically.
- **Mobile-First Templates**: Optimized for standard email clients.
- **High Performance**: Zero-overhead queueing and batching.

---

🤝 Contributing & Security
-----------------------------

[](#-contributing--security)

We welcome contributions! Please see our **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on how to get started.

If you discover a security vulnerability, please review our **[SECURITY.md](SECURITY.md)** for our reporting process.

---

⚖️ License
----------

[](#️-license)

Distributed under the MIT License. © 2026 MonkeysCloud Team

###  Health Score

52

—

FairBetter than 96% of packages

Maintenance97

Actively maintained with recent releases

Popularity22

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity63

Established project with proven stability

 Bus Factor1

Top contributor holds 89.3% 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 ~21 days

Recently: every ~8 days

Total

16

Last Release

16d ago

Major Versions

1.0.7 → v2.x-dev2026-04-09

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2913369?v=4)[Jorge Peraza](/maintainers/yorchperaza)[@yorchperaza](https://github.com/yorchperaza)

---

Top Contributors

[![Amanar-Marouane](https://avatars.githubusercontent.com/u/155680356?v=4)](https://github.com/Amanar-Marouane "Amanar-Marouane (67 commits)")[![yorchperaza](https://avatars.githubusercontent.com/u/2913369?v=4)](https://github.com/yorchperaza "yorchperaza (8 commits)")

---

Tags

psrlogemailnotificationsmarkdownmailersmtpmailingmonkeyslegionphp-mailermonkeyscloudemail-drivermail-integration

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/monkeyscloud-monkeyslegion-mail/health.svg)

```
[![Health](https://phpackages.com/badges/monkeyscloud-monkeyslegion-mail/health.svg)](https://phpackages.com/packages/monkeyscloud-monkeyslegion-mail)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[symfony/symfony

The Symfony PHP framework

31.4k87.2M2.2k](/packages/symfony-symfony)[symfony/mailer

Helps sending emails

1.6k409.1M1.4k](/packages/symfony-mailer)[web-auth/webauthn-lib

FIDO2/Webauthn Support For PHP

12310.5M135](/packages/web-auth-webauthn-lib)[illuminate/mail

The Illuminate Mail package.

5910.6M500](/packages/illuminate-mail)

PHPackages © 2026

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