This page provides a comprehensive reference for all webhook events dispatched by the Lettermint Laravel package.
Event Overview
All webhook events extend the LettermintWebhookEvent base class and contain two main properties:
envelope - Metadata about the webhook event itself
data - Event-specific data payload
Event Types
The following table lists all available webhook event types and their corresponding event classes:
| Event Type | Event Class | Description |
|---|
message.created | MessageCreated | Fired when a new email message is created |
message.sent | MessageSent | Fired when a message is successfully sent to the recipient’s server |
message.delivered | MessageDelivered | Fired when a message is confirmed delivered to the recipient |
message.hard_bounced | MessageHardBounced | Fired when a message permanently bounces |
message.soft_bounced | MessageSoftBounced | Fired when a message temporarily bounces |
message.spam_complaint | MessageSpamComplaint | Fired when a recipient marks a message as spam |
message.failed | MessageFailed | Fired when a message fails to send |
message.suppressed | MessageSuppressed | Fired when a message is suppressed due to suppression list |
message.unsubscribed | MessageUnsubscribed | Fired when a recipient unsubscribes |
message.inbound | MessageInbound | Fired when an inbound email is received |
webhook.test | WebhookTest | Test event for webhook verification |
Common Properties
WebhookEnvelope
All events include an envelope property containing metadata about the webhook event.
Unique identifier for this webhook event.
The type of webhook event (e.g., message.sent, message.delivered).
timestamp
DateTimeImmutable
required
ISO 8601 timestamp when the event occurred.
Event Classes
MessageCreated
Namespace: Lettermint\Laravel\Events\MessageCreated
Triggered when: A new email message is created in Lettermint.
Properties
data
MessageCreatedData
required
Unique identifier for the email message.
Array of recipient email addresses.
Array of CC email addresses.
Array of BCC email addresses.
Array of reply-to email addresses.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
Example
use Lettermint\Laravel\Events\MessageCreated;
Event::listen(MessageCreated::class, function (MessageCreated $event) {
$messageId = $event->data->messageId;
$recipient = $event->data->to[0];
$subject = $event->data->subject;
Log::info("Message {$messageId} created: {$subject}");
});
MessageSent
Namespace: Lettermint\Laravel\Events\MessageSent
Triggered when: A message is successfully sent to the recipient’s mail server.
Properties
Unique identifier for the email message.
Email address of the recipient.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
MessageDelivered
Namespace: Lettermint\Laravel\Events\MessageDelivered
Triggered when: A message is confirmed delivered to the recipient.
Properties
data
MessageDeliveredData
required
Unique identifier for the email message.
Email address of the recipient.
Response from the recipient’s mail server.
SMTP status code (e.g., 250).
Enhanced status code (e.g., “2.0.0”).
Response message from the server.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
MessageFailed
Namespace: Lettermint\Laravel\Events\MessageFailed
Triggered when: A message fails to send.
Properties
data
MessageFailedData
required
Unique identifier for the email message.
Email address of the recipient.
Response from the recipient’s mail server.
Response message from the server.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
MessageHardBounced
Namespace: Lettermint\Laravel\Events\MessageHardBounced
Triggered when: A message permanently bounces (e.g., invalid email address).
Properties
data
MessageHardBouncedData
required
Unique identifier for the email message.
Email address of the recipient.
Response from the recipient’s mail server.
Response message from the server.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
Hard bounces typically indicate permanent delivery issues and the recipient should be removed from your mailing list.
MessageSoftBounced
Namespace: Lettermint\Laravel\Events\MessageSoftBounced
Triggered when: A message temporarily bounces (e.g., mailbox full).
Properties
data
MessageSoftBouncedData
required
Unique identifier for the email message.
Email address of the recipient.
Response from the recipient’s mail server.
Response message from the server.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
Soft bounces are temporary issues. Lettermint will automatically retry delivery.
MessageSpamComplaint
Namespace: Lettermint\Laravel\Events\MessageSpamComplaint
Triggered when: A recipient marks a message as spam.
Properties
data
MessageSpamComplaintData
required
Unique identifier for the email message.
Email address of the recipient who reported spam.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
Spam complaints should be taken seriously. Consider removing the recipient from your mailing list.
MessageSuppressed
Namespace: Lettermint\Laravel\Events\MessageSuppressed
Triggered when: A message is suppressed due to the recipient being on a suppression list.
Properties
data
MessageSuppressedData
required
Unique identifier for the email message.
Email address of the recipient.
Reason for suppression (e.g., “hard_bounce”, “spam_complaint”, “unsubscribe”).
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
MessageUnsubscribed
Namespace: Lettermint\Laravel\Events\MessageUnsubscribed
Triggered when: A recipient unsubscribes from emails.
Properties
data
MessageUnsubscribedData
required
Unique identifier for the email message.
Email address of the recipient who unsubscribed.
unsubscribedAt
DateTimeImmutable
required
Timestamp when the recipient unsubscribed.
metadata
array<string, mixed>
required
Custom metadata attached to the message.
Optional tag for categorizing the message.
MessageInbound
Namespace: Lettermint\Laravel\Events\MessageInbound
Triggered when: An inbound email is received at a Lettermint route.
Properties
data
MessageInboundData
required
The route identifier that received this inbound email.
Unique identifier for the inbound message.
from
InboundEmailAddress
required
Sender email address.
Subaddress (plus addressing) part.
to
array<InboundEmailAddress>
required
Array of recipient email addresses.
cc
array<InboundEmailAddress>
required
Array of CC email addresses.
The email address that received this message.
Subaddress (plus addressing) part of the recipient.
date
DateTimeImmutable
required
Date when the email was sent.
Email body content.
Plain text version of the email.
HTML version of the email.
Optional tag from the route configuration.
attachments
array<EmailAttachment>
required
Array of email attachments.
Name of the attached file.
Base64-encoded file content.
MIME type of the attachment.
Size of the attachment in bytes.
Content-ID for inline attachments.
Whether the email was identified as spam.
spamSymbols
array<SpamSymbol>
required
Array of spam detection symbols.
Score contribution of this symbol.
Additional options for this symbol.
Human-readable description.
Example
use Lettermint\Laravel\Events\MessageInbound;
Event::listen(MessageInbound::class, function (MessageInbound $event) {
$from = $event->data->from->email;
$subject = $event->data->subject;
$body = $event->data->body->text ?? $event->data->body->html;
// Process attachments
foreach ($event->data->attachments as $attachment) {
$filename = $attachment->filename;
$content = $attachment->getDecodedContent();
// Save or process attachment
Storage::put("inbound/{$filename}", $content);
}
Log::info("Received inbound email from {$from}: {$subject}");
});
WebhookTest
Namespace: Lettermint\Laravel\Events\WebhookTest
Triggered when: A webhook test event is sent (used for verification).
Properties
Identifier of the webhook configuration being tested.
Unix timestamp when the test was triggered.
Helper Methods
WebhookEventType Enum
The WebhookEventType enum provides helper methods for event classification:
use Lettermint\Laravel\Webhooks\WebhookEventType;
// Check if event is a bounce
$isBounce = WebhookEventType::MessageHardBounced->isBounce(); // true
$isBounce = WebhookEventType::MessageSoftBounced->isBounce(); // true
// Check if event represents a delivery issue
$isIssue = WebhookEventType::MessageHardBounced->isDeliveryIssue(); // true
$isIssue = WebhookEventType::MessageSoftBounced->isDeliveryIssue(); // true
$isIssue = WebhookEventType::MessageFailed->isDeliveryIssue(); // true
$isIssue = WebhookEventType::MessageSuppressed->isDeliveryIssue(); // true
Listening to Events
You can listen to webhook events in several ways:
Event Listener Class
namespace App\Listeners;
use Lettermint\Laravel\Events\MessageDelivered;
class LogEmailDelivery
{
public function handle(MessageDelivered $event): void
{
logger()->info('Email delivered', [
'message_id' => $event->data->messageId,
'recipient' => $event->data->recipient,
'status_code' => $event->data->response->statusCode,
]);
}
}
Register in EventServiceProvider:
protected $listen = [
MessageDelivered::class => [
LogEmailDelivery::class,
],
];
Closure-based Listener
use Illuminate\Support\Facades\Event;
use Lettermint\Laravel\Events\MessageHardBounced;
Event::listen(MessageHardBounced::class, function (MessageHardBounced $event) {
// Handle hard bounce
User::where('email', $event->data->recipient)
->update(['email_bounced' => true]);
});
Listen to All Events
use Lettermint\Laravel\Events\LettermintWebhookEvent;
Event::listen(LettermintWebhookEvent::class, function (LettermintWebhookEvent $event) {
$envelope = $event->getEnvelope();
logger()->info('Lettermint webhook received', [
'event_type' => $envelope->event->value,
'event_id' => $envelope->id,
'timestamp' => $envelope->timestamp,
]);
});