Keep track of outgoing emails and associate sent emails with Eloquent models

This package helps you to keep track of outgoing emails in your Laravel application. In addition, you can associate Models to the sent out emails.

Here are a few short examples what you can do:

// An email is sent to $user. The passed $product and $user models will be 
// associated with the sent out email generated by the `ProductReviewMail` mailable.
Mail::to($user)->send(new ProductReviewMail($product, $user));

In your application, you can then fetch all sent out emails for the user or the product.

$user->sends()->get();
$product->sends()->get();

Or you can fetch all sent out emails for the given Mailable class.

Send::forMailClass(ProductReviewMail::class)->get();

Each Send-model holds the following information:

• FQN of mailable class
• subject
• from address
• reply to address
• to address
• cc adresses
• bcc adresses

Additionally, the sends-table has the following columns which can be filled by your own application (learn more).

• delivered_at
• last_opened_at
• opens
• clicks
• last_clicked_at
• complained_at
• bounced_at
• permanent_bounced_at
• rejected_at

Installation

You can install the package via composer:

composer require wnx/laravel-sends

Then, publish and run the migrations:

php artisan vendor:publish --tag="sends-migrations"
php artisan migrate

Optionally, you can publish the config file with:

php artisan vendor:publish --tag="sends-config"

This is the contents of the published config file:

return [
    /*
     * The fully qualified class name of the `Send` model.
     */
    'send_model' => \Wnx\Sends\Models\Send::class,

    /**
     * If set to true, the content of sent mails is saved to the database.
     */
    'store_content' => env('SENDS_STORE_CONTENT', false),

    'headers' => [
        /**
         * Header containing the encrypted FQN of the mailable class.
         */
        'mail_class' => env('SENDS_HEADERS_MAIL_CLASS', 'X-Laravel-Mail-Class'),

        /**
         * Header containing an encrypted JSON object with information which
         * Eloquent models are associated with the mailable class.
         */
        'models' => env('SENDS_HEADERS_MAIL_MODELS', 'X-Laravel-Mail-Models'),

        /**
         * Header containing unique ID of the sent out mailable class.
         * Set this to `Message-ID`, if you want to use the Message ID as the unique ID identifing the sent mail.
         */
        'send_uuid' => env('SENDS_HEADERS_SEND_UUID', 'X-Laravel-Send-UUID'),
    ],
];

Usage

After the installation is done, update your applications EventServiceProvider to listen to the MessageSent event. Add the StoreOutgoingMailListener-class as a listener.

// app/Providers/EventServiceProvider.php
protected $listen = [
    // ...
    \Illuminate\Mail\Events\MessageSent::class => [
        \Wnx\Sends\Listeners\StoreOutgoingMailListener::class,
    ],
]

The metadata of all outgoing emails created by mailables or notifications is now being stored in the sends-table. (Note that you can only associate models to mailables; but not to notifiations)

Read further to learn how to store the name and how to associate models with a Mailable class.

Store Mailable class name on Send Model

By default the Event Listener stores the mails subject and the recipient adresses. That's nice, but we can do better. It can be beneficial for your application to know which Mailable class triggered the sent email.

To store this information, add the StoreMailables-trait to your Mailable classes like below. You now have access to a couple of helper methods.

Depending on how you write Mailables, there a different ways to use these new methods. Call the storeClassName-method inside the build-method of your Mailable.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(public User $user, public Product $product)
    {
    }

    public function build()
    {
        return $this
            ->storeClassName()
            ->view('emails.products.review')
            ->subject("$this->product->name waits for your review");
    }
}

If you use the Mailable syntax introduced in Laravel v9.35, you can either use $this->storeClassName() in the headers-method or pass $this->getMailClassHeader()->toArray() to the Header object.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(
        public User $user,
        public Product $product
    ) { }

    // ...

    /**
     * @return \Illuminate\Mail\Mailables\Headers
     */
    public function headers()
    {
        // Call storeClassName() and let the package take care of adding the
        // header to the outgoing mail.
        $this->storeClassName();

        // Or – if you want more control – use the getMailClassHeader() method
        // to get a Header instance and merge it with your own headers.
        return new Headers(
            text: [
                'X-Custom-Header' => 'Custom Value',
                ...$this->getMailClassHeader()->toArray(),
            ],
        );
    }
}

The method will add a X-Laravel-Mail-Class-header to the outgoing email containing the fully qualified name (FQN) of the Mailable class as an encrypted string. (eg. App\Mails\ProductReviewMail). Update the SENDS_HEADERS_MAIL_CLASS-env variable to adjust the header name. (See config for details).

The package's event listener will then look for the header, decrypt the value and store it in the database.

Associate Sends with Related Models

Now that you already keep track of all outgoing emails, wouldn't it be great if you could access the records from an associated Model? In the example above we send a ProductReviewMail to a user. Wouldn't it be great to see how many emails you have sent for a given Product-model?

To achieve this, you have to add the HasSends-interface and the HasSendsTrait trait to your models.

use Wnx\Sends\Contracts\HasSends;
use Wnx\Sends\Support\HasSendsTrait;

class Product extends Model implements HasSends
{
    use HasSendsTrait;
}

You can now call the associateWith()-method within the build()-method. Pass the Models you want to associate with the Mailable class to the method as arguments. Instead of passing the Models as arguments, you can also pass them as an array.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(
        private User $user,
        private Product $product
    ) { }

    public function build()
    {
        return $this
            ->storeClassName()
            ->associateWith($this->product)
            // ->associateWith([$this->product])
            ->view('emails.products.review')
            ->subject("$this->user->name, $this->product->name waits for your review");
    }
}

If you're using the Mailable syntax introduced in Laravel v9.35, you can call associateWith() or getMailModelsHeader() in the headers-method too.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(
        private User $user,
        private Product $product
    ) { }

    // ...

    /**
     * @return \Illuminate\Mail\Mailables\Headers
     */
    public function headers()
    {
        // Call associateWith() and the package automatically associates the public
        // properties with this mailable.
        $this->associateWith($this->product);
        $this->associateWith([$this->product]);

        // Or – if you want more control – use the getMailModelsHeader() method
        // to get a Header instance and merge it with your own headers.
        return new Headers(
            text: [
                'X-Custom-Header' => 'Custom Value',
                ...$this->getMailModelsHeader($this->product)->toArray(),
                ...$this->getMailModelsHeader([$this->product])->toArray(),
            ],
        );
    }
}

You can now access the sent out emails from the product's sends-relationship.

$product->sends()->get();

Automatically associate Models with Mailables

If you do not pass an argument to the associateWith-method, the package will automatically associate all public properties which implement the HasSends-interface with the Mailable class. 🪄

In the example below, the ProductReviewMail-Mailable will automatically be associated with the $product Model, as Product implements the HasSends interface. The $user model will be ignored, as it's declared as a private property.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(
        private User $user, 
        public Product $product
    ) { }

    public function build()
    {
        return $this
            ->associateWith()
            ->view('emails.products.review')
            ->subject("$this->user->name, $this->product->name waits for your review");
    }
}

If you're using the Mailable syntax introduced in Laravel v9.35, you can call associateWith() or getMailModelsHeader() in the headers-method.

class ProductReviewMail extends Mailable
{
    use SerializesModels;
    use StoreMailables;

    public function __construct(
        private User $user,
        public Product $product
    ) { }

    // ...

    /**
     * @return \Illuminate\Mail\Mailables\Headers
     */
    public function headers()
    {
        // Call associateWith() and the package automatically associates the public
        // properties with this mailable.
        $this->associateWith();

        // Or – if you want more control – use the getMailModelsHeader() method
        // to get a Header instance and merge it with your own headers.
        return new Headers(
            text: [
                'X-Custom-Header' => 'Custom Value',
                ...$this->getMailModelsHeader()->toArray(),
            ],
        );
    }
}

Attach custom Message ID to Mails

If you're sending emails through AWS SES or a similar service, you might want to identify the sent email in the future (for example when a webhook for the "Delivered"-event is sent to your application).

The package comes with an event listener helping you here. Update the EventServiceProvider to listen to the MessageSending event and add the AttachSendUuidListener as a listener. A X-Laravel-Message-UUID header will be attached to all outgoing emails. The header contains a UUID value. (This value can not be compared to the Message-ID defined in RFC 2392)
You can then use the value of X-Laravel-Message-UUID or $send->uuid later in your application.

// app/Providers/EventServiceProvider.php
protected $listen = [
    // ...
    \Illuminate\Mail\Events\MessageSending::class => [
        \Wnx\Sends\Listeners\AttachSendUuidListener::class,
    ],
]

(If you want to store the value of Message-ID in your database, do not add the event listener but update the SENDS_HEADERS_SEND_UUID-env variable to Message-ID. The StoreOutgoingMailListener will then store the Message-ID in the database.)

Store Content of Mails

By default, the package does not store the content of sent out emails. By setting the sends.store_content configuration value to true, the body of all outgoing mails is stored in the content-column in the sends database table.

/**
 * If set to true, the contet of sent mails is saved to the database.
 */
'store_content' => true,

SENDS_STORE_CONTENT=true

Customize Attributes stored in Send Models

If you need to store more attributes with your Send-model, you can extend the StoreOutgoingMailListener and override the getSendAttributes-method.

For example, let's say we would like to store an audience-value with each sent out email. We create a new Event Listener called CustomStoreOutgoingMailListener and use the class as Listener to the MessageSent-event.

Our EventServiceProvider would look like this.

// app/Providers/EventServiceProvider.php
protected $listen = [
    // ...
    \Illuminate\Mail\Events\MessageSent::class => [
        \App\Listeners\CustomStoreOutgoingMailListener::class,
    ],
]

The Listener itself would look like the code below. We extend Wnx\Sends\Listeners\StoreOutgoingMailListener and override getSendAttributes. We merge the $defaultAttributes with our custom attributes we want to store. In the example below we store an audience value.

<?php

namespace App\Listeners;

use Illuminate\Mail\Events\MessageSent;
use Wnx\Sends\Listeners\StoreOutgoingMailListener;

class CustomStoreOutgoingMailListener extends StoreOutgoingMailListener
{
    protected function getSendAttributes(MessageSent $event, array $defaultAttributes): array
    {
        return array_merge($defaultAttributes, [
            'audience' => $this->getAudience($event),
        ]);
    }

Prune Send Models

By default, Send-models are kept forever in your database. If your application sends thousands of emails per day, you might want to prune records after a couple of days or months.

To do that, use the prunable feature of Laravel.

Create a new Send-model in your app/Models that extends Wnx\Sends\Models\Send. Then add the Prunable-trait and set up the prunable()-method to your liking. The example below deletes all Send-models older than 1 month.

// app/Models/Send.php
namespace App\Models;

use Illuminate\Database\Eloquent\Prunable;
use Wnx\Sends\Models\Send as BaseSend;

class Send extends BaseSend
{
    use Prunable;

    public function prunable()
    {
        return static::where('created_at', '<=', now()->subMonth());
    }
}

Optionally you can also update the configuration, so that the package internally uses your Send model.

// config/sends.php
/*
 * The fully qualified class name of the send model.
 */
'send_model' => \App\Models\Send::class,

Further Usage of the sends-table

As you might have noticed, the sends-table comes with more columns than that are currently filled by the package. This is by design.

You are encouraged to write your own application logic to fill these currently empty columns. For example, if you're sending emails through AWS SES, I highly encourage you to use the renoki-co/laravel-aws-webhooks package to handle AWS SNS webhooks.

A controller that handles the "Delivered" event might look like this.

class AwsSnsSesWebhookController extends SesWebhook {
    protected function onDelivery(array $message)
    {
        $uuidHeader = collect(Arr::get($message, 'mail.headers', []))
            ->firstWhere('name', config('sends.headers.send_uuid'));

        if ($uuidHeader === null) {
            return;
        }

        $send = Send::forUuid($uuidHeader['value'])->first();

        if ($send === null) {
            return;
        }

        $send->delivered_at = now();
        $send->save();
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Stefan Zweifel
• All Contributors

License

The MIT License (MIT). Please see License File for more information.