Overview

Purpose and Scope

This document provides a high-level introduction to the hypervel/mail package, a comprehensive email system for the Hypervel framework. It covers the package's architecture, core components, integration points, and capabilities for sending emails through multiple transport mechanisms.

For detailed information on specific subsystems:

• Installation and configuration: see Installation and Setup and Configuration
• Core architecture details: see Core Architecture
• Creating and sending emails: see Working with Mailables
• Template rendering: see Content Rendering System
• Testing: see Testing Emails

---

Package Identity

The hypervel/mail package is a mail system built for the Hypervel ecosystem, leveraging Symfony Mailer as its transport engine while providing Laravel-style mailable abstractions and Hyperf framework integration.

Package Metadata:

Property	Value
Name	hypervel/mail
Type	Library
License	MIT (based on Laravel's mail system)
PHP Version	^8.2
Primary Namespace	Hypervel\Mail

Sources: composer.json1-11 LICENSE.md1-6

---

Architectural Overview

The mail system is organized into six primary layers that work together to enable email delivery:

Sources: composer.json23-41

---

Core Components

Factory and Management

The MailManager class implements the factory pattern to create and manage Mailer instances based on configuration. It resolves transport drivers, manages connection pooling, and provides access to configured mailers.

Key Classes:

• MailManager: Factory for creating configured Mailer instances
• Mailer: Core dispatcher that coordinates message preparation, rendering, and transmission
• ConfigProvider: Hyperf configuration provider for dependency injection setup

Sources: Referenced from architecture diagrams

Message Abstraction

The Mailable class provides a high-level abstraction for email messages, allowing developers to define email content, recipients, and attachments in a declarative manner. The PendingMail class provides a fluent interface for recipient configuration before sending.

Key Classes:

• Mailable: Abstract base class for email message definitions
• PendingMail: Fluent interface for recipient and delivery configuration
• Envelope: Data class for message metadata (subject, recipients, tags)
• Attachment: Abstraction for file attachments

Sources: Referenced from architecture diagrams

---

Transport Ecosystem

The package supports 10+ transport drivers, organized into four categories:

Category	Transports	Purpose
Direct	EsmtpTransport, SendmailTransport	SMTP servers and local sendmail
API-Based	SesTransport, SesV2Transport, MailgunTransport, PostmarkTransport	Cloud email services via HTTP APIs
Composite	FailoverTransport, RoundRobinTransport	High availability and load distribution
Development	LogTransport, ArrayTransport	Testing and debugging

All transports implement Symfony's TransportInterface, ensuring consistent behavior and interoperability.

Sources: composer.json54-58

---

Dependency Architecture

The package integrates with multiple ecosystems to provide comprehensive email functionality:

Dependency Categories:

Category	Packages	Purpose
Hyperf Framework	hyperf/di, hyperf/collection, hyperf/view-engine, etc.	Framework foundation, dependency injection, view rendering
Hypervel Ecosystem	hypervel/support, hypervel/filesystem, hypervel/object-pool	Utilities, file storage, connection pooling
Symfony Mailer	symfony/mailer, optional transport bridges	Core transport engine and protocol implementations
External Libraries	league/commonmark, tijsverkoyen/css-to-inline-styles	Markdown parsing, CSS inlining for email clients
Optional Services	aws/aws-sdk-php, symfony/mailgun-mailer, symfony/postmark-mailer	Cloud service integrations

Sources: composer.json28-58

---

Message Lifecycle

The following diagram illustrates the complete flow of an email from creation through delivery:

Key Lifecycle Phases:

1. Creation: Instantiate a Mailable subclass
2. Configuration: Set recipients via PendingMail fluent API or Envelope
3. Dispatch: Choose synchronous (send()) or asynchronous (queue()) delivery
4. Preparation: Execute build() method and hydrate message properties
5. Rendering: Process Blade views, parse Markdown, inline CSS styles
6. Events: Dispatch MessageSending (can cancel) and MessageSent events
7. Transmission: Send via configured Transport driver

Sources: Referenced from architecture diagrams

---

Key Features

Multi-Transport Support

The package provides seamless integration with 10+ transport drivers, supporting SMTP, AWS SES (v1 and v2), Mailgun, Postmark, and local transports. High availability is achieved through FailoverTransport and RoundRobinTransport composite strategies.

Content Rendering Pipeline

Emails can be authored using:

• Blade Templates: Full Hyperf view engine integration with data binding
• Markdown: CommonMark parser with automatic HTML conversion
• Blade Components: Reusable <x-mail::*> components for consistent email UI
• CSS Inlining: Automatic style embedding for email client compatibility

Queue Integration

The Mailable class integrates with hypervel/queue, allowing deferred email delivery through the SendQueuedMailable job. This supports:

• Background email processing
• Retry logic with exponential backoff
• Priority-based queue assignment
• Delayed email scheduling

Event System

The package dispatches PSR-14 events at key lifecycle points:

• MessageSending: Fired before transmission (can prevent delivery)
• MessageSent: Fired after successful transmission

These events enable logging, analytics, delivery verification, and conditional sending logic.

Performance Optimization

Connection pooling via hypervel/object-pool ensures efficient resource utilization for SMTP and API-based transports, reducing connection overhead in high-throughput scenarios.

Sources: composer.json28-58

---

Configuration-Driven Architecture

The package uses a declarative configuration system (mail.php) to define:

• Mailers: Named mail configurations (e.g., smtp, ses, log)
• Default Mailer: System-wide default transport
• Global Settings: From address, reply-to, CC/BCC recipients
• Transport Options: Driver-specific parameters (host, port, credentials, API keys)

The MailManager reads this configuration and dynamically instantiates the appropriate transport drivers with pooling and failover strategies as specified.

Sources: Referenced from architecture diagrams

---

Integration Points

The mail system integrates with the Hypervel/Hyperf ecosystem at multiple points:

Integration	Component	Purpose
Dependency Injection	hyperf/di	Service container registration via ConfigProvider
Views	hyperf/view-engine	Blade template rendering for email bodies
Filesystem	hypervel/filesystem	Attachment loading from storage disks
Queue	hypervel/queue	Asynchronous email delivery
Events	PSR-14 dispatcher	Lifecycle event broadcasting
Logging	PSR-3 logger	Development transport and error logging
Object Pooling	hypervel/object-pool	Transport connection management

Sources: composer.json28-41

---

Design Principles

The package adheres to several architectural principles:

1. Separation of Concerns: Transport logic (Symfony), framework integration (Hyperf), and high-level abstractions (Mailable) are cleanly separated
2. Factory Pattern: MailManager encapsulates complex transport instantiation logic
3. Fluent Interface: PendingMail provides chainable methods for intuitive configuration
4. Strategy Pattern: Multiple transport drivers implement TransportInterface
5. Event-Driven: Lifecycle hooks enable extensibility without modifying core classes
6. Testability: ArrayTransport and LogTransport facilitate testing without external dependencies

Sources: Referenced from architecture diagrams and composer.json28-58