Skip to main content
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 TypeEvent ClassDescription
message.createdMessageCreatedFired when a new email message is created
message.sentMessageSentFired when a message is successfully sent to the recipient’s server
message.deliveredMessageDeliveredFired when a message is confirmed delivered to the recipient
message.hard_bouncedMessageHardBouncedFired when a message permanently bounces
message.soft_bouncedMessageSoftBouncedFired when a message temporarily bounces
message.spam_complaintMessageSpamComplaintFired when a recipient marks a message as spam
message.failedMessageFailedFired when a message fails to send
message.suppressedMessageSuppressedFired when a message is suppressed due to suppression list
message.unsubscribedMessageUnsubscribedFired when a recipient unsubscribes
message.inboundMessageInboundFired when an inbound email is received
webhook.testWebhookTestTest event for webhook verification

Common Properties

WebhookEnvelope

All events include an envelope property containing metadata about the webhook event.
id
string
required
Unique identifier for this webhook event.
event
WebhookEventType
required
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

envelope
WebhookEnvelope
required
Event metadata.
data
MessageCreatedData
required

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

envelope
WebhookEnvelope
required
Event metadata.
data
MessageSentData
required

MessageDelivered

Namespace: Lettermint\Laravel\Events\MessageDelivered Triggered when: A message is confirmed delivered to the recipient.

Properties

envelope
WebhookEnvelope
required
Event metadata.
data
MessageDeliveredData
required

MessageFailed

Namespace: Lettermint\Laravel\Events\MessageFailed Triggered when: A message fails to send.

Properties

envelope
WebhookEnvelope
required
Event metadata.
data
MessageFailedData
required

MessageHardBounced

Namespace: Lettermint\Laravel\Events\MessageHardBounced Triggered when: A message permanently bounces (e.g., invalid email address).

Properties

envelope
WebhookEnvelope
required
Event metadata.
data
MessageHardBouncedData
required
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

envelope
WebhookEnvelope
required
Event metadata.
data
MessageSoftBouncedData
required
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

envelope
WebhookEnvelope
required
Event metadata.
data
MessageSpamComplaintData
required
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

envelope
WebhookEnvelope
required
Event metadata.
data
MessageSuppressedData
required

MessageUnsubscribed

Namespace: Lettermint\Laravel\Events\MessageUnsubscribed Triggered when: A recipient unsubscribes from emails.

Properties

envelope
WebhookEnvelope
required
Event metadata.
data
MessageUnsubscribedData
required

MessageInbound

Namespace: Lettermint\Laravel\Events\MessageInbound Triggered when: An inbound email is received at a Lettermint route.

Properties

envelope
WebhookEnvelope
required
Event metadata.
data
MessageInboundData
required

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

envelope
WebhookEnvelope
required
Event metadata.
data
WebhookTestData
required

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,
    ]);
});

Build docs developers (and LLMs) love