PHPackages                             waynebrummer/mail-telemetry - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. waynebrummer/mail-telemetry

ActiveLibrary[Mail & Notifications](/categories/mail)

waynebrummer/mail-telemetry
===========================

Logs mail transactions and provides a report for email telemetry.

1.0.4(6y ago)0321Apache-2.0PHPPHP ^7.2

Since Oct 22Pushed 5y ago1 watchersCompare

[ Source](https://github.com/WayneBrummer/mail-telemetry)[ Packagist](https://packagist.org/packages/waynebrummer/mail-telemetry)[ RSS](/packages/waynebrummer-mail-telemetry/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (5)Dependencies (7)Versions (6)Used By (0)

Laravel Mail Telemetry
======================

[](#laravel-mail-telemetry)

Mail Telemetry will hook into all outgoing emails (unless otherwise stated) from Laravel and inject a tracking pixel and links into it.

It will also store the rendered email in the database for review and analytics.

Install
-------

[](#install)

Via Composer:

```
composer require waynebrummer/mail-telemetry
```

Publish the config file and migration:

```
php artisan vendor:publish --provider="Pace\MailTelemetry\ServiceProvider"
```

Run the migration:

```
php artisan migrate
```

**Note**: If you would like to use a different connection to store your models, you should update the `mail-telemetry.php` config entry `connection` before running the migrations.

---

Usage
-----

[](#usage)

Once installed, all outgoing mail will be logged to the database.

The following config options are available in `config/mail-telemetry.php`:

- **pixel**: Set to `true` or `false` to inject a tracking pixel into all outgoing html emails.
- **links**: Set to `true` or `false` to overwrite all anchor href tags to include a tracking link.

    - The link will take the user back to your website which will then redirect them to the final destination after logging the click.
- **expire-days**: How long in days that an email should be retained in your database.

    - If you are sending a lot of mail, you probably want it to eventually expire.
        - Set it to `zero` `(0)` to never purge old emails from the database.
- **route**: The route information for the tracking URLs.

    - Set the prefix and middleware as desired.
- **auth-route**: The route information for the admin.

    - Set the prefix and middleware.
- **log-content**: Set to `true` or `false` to record the physical email sent.
- **emails-per-page**: The default amount of emails to display for the endpoint.

    - Numerical value of users choice. Set to JSON API standards.
- **date-format**: You can define the format to show dates in the Admin Panel.

If you do not wish to have an email tracked, then you can add the `X-No-Track` header to your message. Put any random string into this header to prevent the tracking from occurring. The header will be removed from the email prior to being sent.

```
\Mail::send('email.test', [], function ($message) {
    // ... other settings here
    $message->getHeaders()->addTextHeader('X-No-Track',Str::random(10));
});
```

---

\*\* Linking to Notifications table.

If you wish to have an email linked to the Notification model, then you can add the `X-Email-Notification-ID` header to your message. This will contain the Notification ID just used.

```
\Mail::send('email.test', [], function ($message) {
    // ... other settings here
    $message->getHeaders()->addTextHeader('X-Email-Notification-ID',$this->id);
});
```

or if you love the power of the Notifiable Trait. YOu can change your toMail function to request a Mailable.

```
/**
 * Mailable function returned.
 *
 * @param mixed $notifiable
 *
 * @return \App\Mail\AssignedToMail
 */
public function toMail($notifiable) : \App\Mail\AssignedToMail
{
    return new AssignedToMail($notifiable, $this->model, $this->id);
}
```

Then in the Mailable you can reference MailMessage class.

The `build` method will then be used to inject the `'X-Email-Notification-ID'` into the email

```
/**
 * Build the message.
 *
 * @return $this
 */
public function build()
{
    $this->withSwiftMessage(function ($message) {
        $message->getHeaders()->addTextHeader('X-Email-Notification-ID', $this->notification);
    });
    return $this->to($this->user->email)
        ->subject("Assignment: {$this->user->first_name} {$this->user->last_name},")
        ->markdown('vendor.notifications.email', $this->message->data());
}
```

---

***Note on local development testing***
---------------------------------------

[](#note-on-local-development-testing)

Several people have reporting the tracking pixel not working while they were testing. What is happening with the tracking pixel is that the email client is connecting to your website to log the view. In order for this to happen, images have to be visible in the client, and the client has to be able to connect to your server.

When you are in a local dev environment (i.e. using the `.test` domain with Valet, or another domain known only to your computer) you must have an email client on your computer.

Further complicating this is the fact that Gmail and some other web-based email clients don't connect to the images directly, but instead connect via proxy.

That proxy won't have a connection to your `.test` domain and therefore will not properly track emails. I always recommend using [mailtrap.io](https://mailtrap.io) for any development environment when you are sending emails. Not only does this solve the issue (mailtrap.io does not use a proxy service to forward images in the emails) but it also protects you from accidentally sending real emails from your test environment.

Events
------

[](#events)

When an email is sent, viewed, or a link is clicked, its tracking information is counted in the database using the `Pace\MailTelemetry\Models\Email` model.

You may want to do additional processing on these events, so an event is fired in these cases:

- Pace\\MailTelemetry\\Events\\EmailEvent

If you are using the Amazon SNS notification system, an event is fired when you receive a permanent bounce. You may want to mark the email as bad or remove it from your database.

- Pace\\MailTelemetry\\Events\\PermanentBouncedMessageEvent

To install an event listener, you will want to create a file like the following:

```
php artisan make:listener EmailViewed
```

```