Event System

The Event System provides hooks into the mail sending lifecycle through two PSR-14 compatible events: MessageSending and MessageSent. These events allow application code to inspect messages before they are sent, prevent sending under certain conditions, and react to successfully sent messages.

This page documents the event classes, dispatch flow, and integration patterns. For the complete message sending lifecycle, see Message Lifecycle. For information about queue-based event handling, see Queue Integration.

---

Event Classes

The mail system dispatches two events during the sending process, both located in the Hypervel\Mail\Events namespace.

MessageSending Event

Property	Type	Description
$message	Symfony\Component\Mime\Email	The Symfony Email instance being sent
$data	array	Contextual data including view data and mailer name
$shouldSend	bool	Flag controlling whether sending proceeds (default: true)

The MessageSending event is dispatched immediately before the message is handed to the transport layer. Event listeners can inspect the message content, modify the $shouldSend property to prevent delivery, or perform side effects such as logging.

This method returns the current value of the $shouldSend property, which the Mailer checks to determine if transport dispatch should proceed.

Sources: src/Events/MessageSending.php9-29

MessageSent Event

Property	Type	Description
$sent	Hypervel\Mail\SentMessage	Wrapper containing the Symfony SentMessage
$data	array	Contextual data from the sending process

The MessageSent event is dispatched after the transport successfully sends the message. It provides access to transport-specific metadata such as message IDs through the SentMessage wrapper.

The event implements custom serialization logic to handle attachments efficiently. When attachments are present, the $data array is base64-encoded during serialization:

A magic __get method provides backward-compatible access to the original Symfony message:

Sources: src/Events/MessageSent.php11-60

---

Event Dispatch Flow

The following diagram illustrates when events are dispatched during the mail sending process:

Title: Event Dispatch During Message Sending

Sources: src/Mailer.php215-264 src/Mailer.php464-483

---

Preventing Message Sending

Event listeners can prevent message delivery by setting the $shouldSend property to false on the MessageSending event. This mechanism is useful for:

• Rate limiting or throttling
• Conditional sending based on business rules
• Testing and development environments
• Compliance checks before delivery

Implementation in Mailer

The Mailer class checks the event's send status before dispatching to the transport:

Title: Message Sending Prevention Flow

The relevant code in the Mailer class:

When shouldSend() returns false, the send() method skips transport dispatch and returns null instead of a SentMessage instance.

Sources: src/Mailer.php464-473 src/Mailer.php251-263

---

Listening to Events

Event listeners are registered through Hyperf's PSR-14 event dispatcher system. The Mailer receives an optional EventDispatcherInterface instance during construction:

Event Listener Registration

Listeners can be registered in your application's event configuration. Here's a mapping of common use cases to listener implementations:

Use Case	Event	Listener Action
Logging sent emails	MessageSent	Log message details and recipients
Audit trail	MessageSent	Store message metadata in database
Conditional blocking	MessageSending	Set $shouldSend = false based on conditions
Rate limiting	MessageSending	Check rate limits and prevent if exceeded
Content inspection	MessageSending	Scan message for compliance issues
Metrics collection	Both	Track send attempts and success rates

Example: Preventing Sending

Example: Logging Sent Messages

Sources: src/Mailer.php70-76

---

Event Data Context

Both events receive a $data array containing contextual information about the sending operation. The contents vary based on how the mail was sent:

Data Array Contents

Key	Type	Description	Available In
mailer	string	Name of the mailer configuration used	Both events
message	Message	The Message wrapper instance	Both events (via Symfony Email)
View data	mixed	Any data passed to view rendering	Both events
Custom keys	mixed	Application-specific data from callbacks	Both events

When sending via the send() method:

The $data array is preserved throughout the sending process and made available to both events, allowing listeners to access rendering context and other metadata.

Sources: src/Mailer.php221-228 src/Mailer.php470-472 src/Mailer.php478-482

---

Event Dispatch Points in Sending Methods

The following table maps the various sending methods to their event behavior:

Method	MessageSending Dispatched	MessageSent Dispatched	Can Prevent
send()	Yes	Yes (if sent)	Yes
sendNow()	Yes	Yes (if sent)	Yes
html()	Yes	Yes (if sent)	Yes
raw()	Yes	Yes (if sent)	Yes
plain()	Yes	Yes (if sent)	Yes
queue()	No*	No*	N/A
later()	No*	No*	N/A

*Queued messages dispatch events when the queue worker processes them, not during the initial queue() call.

Queued Message Event Flow

Title: Event Dispatch in Queued Sending

When using the queue() or later() methods, events are dispatched during queue worker execution, not during the initial method call. This means event listeners will execute in the queue worker's process context, not the web request context.

Sources: src/Mailer.php215-264 src/Mailer.php366-377 src/Mailer.php402-412

---

Event Dispatcher Dependency

The Mailer class gracefully handles the absence of an event dispatcher. When the $events constructor parameter is null, event-related methods skip dispatching:

This design allows the mail system to function in environments where event dispatching is not available or desired.

Sources: src/Mailer.php464-483

---

Summary of Event Classes

Title: Event Class Relationships

Sources: src/Events/MessageSending.php9-29 src/Events/MessageSent.php11-60 src/Mailer.php464-483