Download the PHP package wnx/laravel-sends without Composer

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:

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

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

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:

Then, publish and run the migrations:

Optionally, you can publish the config file with:

This is the contents of the published config file:

Usage

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

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.

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.

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.

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.

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

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

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.

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

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.

(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.

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.

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.

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.

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

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.

Testing

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.