MailTracker

https://github.com/jdavidbakr/mail-tracker
Admin
MailTracker is a Laravel package that hooks into outgoing emails, injects a tracking code, stores...
Tokens:2,182
Snippets:19
Trust Score:8.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install MailTracker via Composer

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Installs the MailTracker package using Composer. This is the primary method for adding the package to your Laravel project.

```bash
composer require jdavidbakr/mail-tracker
```

--------------------------------

### Run Project Tests with Composer

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/CONTRIBUTING.md

This command executes the project's test suite using Composer. Ensure Composer is installed and the project dependencies are met before running.

```bash
$ composer test
```

--------------------------------

### Publish MailTracker Config and Migrations

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Publishes the MailTracker configuration file and database migration files to your Laravel project. This allows for customization and database setup.

```bash
php artisan vendor:publish --provider="jdavidbakr\MailTracker\MailTrackerServiceProvider"
```

--------------------------------

### Custom Sent Email Model Implementation

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Provides an example of a custom Eloquent model that implements the `SentEmailModel` interface for Mail Tracker. It includes necessary traits and cast definitions for proper integration.

```php
use Illuminate\Database\Eloquent\Model;
use jdavidbakr\MailTracker\Concerns\IsSentEmailModel;
use jdavidbakr\MailTracker\Contracts\SentEmailModel;

class OwnEmailSentModel extends Model implements SentEmailModel {
    use IsSentEmailModel;

    protected static $unguarded = true;

    protected $casts = [
        'meta' => 'collection',
        'opened_at' => 'datetime',
        'clicked_at' => 'datetime',
    ];
}
```

--------------------------------

### Retrieve Custom Header in Email Event Listener

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

This snippet shows how to retrieve a custom header ('X-Model-ID') from an 'EmailSentEvent' in a listener. It accesses the 'sent_email' property of the event to get the email details and then retrieves the header value. The retrieved ID is then used to find a corresponding model.

```php
public function handle(EmailSentEvent $event)
{
    $tracker = $event->sent_email;
    $model_id = $event->sent_email->getHeader('X-Model-ID');
    $model = Model::find($model_id);
    // Perform your tracking/linking tasks on $model knowing the SentEmail object
}
```

--------------------------------

### Publish Vendor Files and Run Migrations (Upgrade)

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Commands to re-publish vendor files and run migrations when upgrading MailTracker from older versions. This ensures configuration and database schema are up-to-date.

```bash
php artisan vendor:publish
```

```bash
php artisan migrate
```

--------------------------------

### Run MailTracker Migrations

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Executes the database migrations published by MailTracker. This creates the necessary tables in your database to store email tracking information.

```bash
php artisan migrate
```

--------------------------------

### Configure Mail Tracker Content Logging to Filesystem

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Shows how to configure the Mail Tracker package to log email content to the filesystem instead of the database. This can help manage database size and performance when sending a high volume of emails.

```php
'log-content-strategy' => 'filesystem',
'tracker-filesystem' => null
'tracker-filesystem-folder' => 'mail-tracker',
```

--------------------------------

### PHP Event Listener for Email Viewed

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

This PHP code demonstrates how to create an event listener for the ViewEmailEvent. It shows how to access the SentEmail model and IP address from the event object. Dependencies include the jdavidbakrMailTrackerEventsViewEmailEvent class.

```php
<?php

namespace App\Listeners;

use jdavidbakr\MailTracker\Events\ViewEmailEvent;

class EmailViewed
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  ViewEmailEvent  $event
     * @return void
     */
    public function handle(ViewEmailEvent $event)
    {
        // Access the model using $event->sent_email
        // Access the IP address that triggered the event using $event->ip_address
    }
}

```

--------------------------------

### Upgrade MailTracker to Version 2.2

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Composer command to upgrade MailTracker to version 2.2. This is a prerequisite for upgrading to later versions if you are on 2.0 or earlier.

```bash
composer require jdavidbakr/mail-tracker ~2.2
```

--------------------------------

### Skip Tracking for Anti-virus/Spam Filters using Event Listener

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Shows how to implement an event listener for `ValidActionEvent` to skip tracking for specific user agents, preventing anti-virus or spam filters from triggering tracking pixels or links.

```php
class ValidUserListener {
    public function handle(ValidActionEvent $event)
    {
        if (in_array(request()->userAgent(), ['Mozilla/5.0', 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.135 Safari/537.36 Edge/12.246 Mozilla/5.0'])) {
            $event->skip = true;
        }
    }
}
```

--------------------------------

### PHP Event Listener for Bounced Email

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

This PHP code illustrates creating an event listener for the PermanentBouncedMessageEvent. It shows how to access the email address associated with the bounce event. The listener depends on the jdavidbakrMailTrackerEventsPermanentBouncedMessageEvent class.

```php
<?php

namespace App\Listeners;

use jdavidbakr\MailTracker\Events\PermanentBouncedMessageEvent;

class BouncedEmail
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  PermanentBouncedMessageEvent  $event
     * @return void
     */
    public function handle(PermanentBouncedMessageEvent $event)
    {
        // Access the email address using $event->email_address
    }
}

```

--------------------------------

### Migrate MailTracker Recipients (Upgrade)

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

A bash command to migrate existing recipient and sender data to the new format when upgrading MailTracker from version 4.x to 5.x. This ensures data integrity after schema changes.

```bash
php artisan mail-tracker:migrate-recipients
```

--------------------------------

### Registering Mail Tracker Event Listeners in Laravel

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

This PHP snippet shows how to register various mail tracker events with their corresponding listeners in the $listen array within Laravel's EventServiceProvider. This configuration is essential for the application to react to dispatched email events.

```php
/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'jdavidbakr\MailTracker\Events\EmailSentEvent' => [
        'App\Listeners\EmailSent',
    ],
    'jdavidbakr\MailTracker\Events\ViewEmailEvent' => [
        'App\Listeners\EmailViewed',
    ],
    'jdavidbakr\MailTracker\Events\LinkClickedEvent' => [
        'App\Listeners\EmailLinkClicked',
    ],
    'jdavidbakr\MailTracker\Events\EmailDeliveredEvent' => [
        'App\Listeners\EmailDelivered',
    ],
    'jdavidbakr\MailTracker\Events\ComplaintMessageEvent' => [
        'App\Listeners\EmailComplaint',
    ],
    'jdavidbakr\MailTracker\Events\PermanentBouncedMessageEvent' => [
        'App\Listeners\BouncedEmail',
    ],
];

```

--------------------------------

### Override Mail Tracker Models in AppServiceProvider

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Illustrates how to override the default sent email and URL clicked models used by Mail Tracker. This allows for custom model implementations while leveraging the package's provided traits.

```php
MailTracker::useSentEmailModel(YourOwnSentEmailModel::class);
MailTracker::useSentEmailUrlClickedModel(YourOwnSentEmailUrlClickedModel::class);
```

--------------------------------

### Prevent Email Tracking with X-No-Track Header

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Demonstrates how to prevent a specific email from being tracked by adding the 'X-No-Track' header. This is useful for excluding certain communications from the tracking system.

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

--------------------------------

### Skip Tracking for Specific Mailable Class

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Demonstrates how to prevent tracking for a specific Mailable class in Laravel 9+ by implementing the `headers` method to include the 'X-No-Track' header.

```php
public function headers()
{
    return [
        'X-No-Track' => Str::random(10),
    ];
}
```

--------------------------------

### Ignore MailTracker Migrations in Laravel

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

Provides a PHP code snippet to instruct MailTracker to ignore its own migrations. This is useful if you intend to manage your own database schema for email tracking.

```php
// In AppServiceProvider

public function register()
{
    MailTracker::ignoreMigrations();
}
```

--------------------------------

### Add Custom Header to Outgoing Email in PHP

Source: https://github.com/jdavidbakr/mail-tracker/blob/master/README.md

This snippet demonstrates how to add a custom header ('X-Model-ID') to an outgoing email using the Mail::send method in PHP. This header can be used to link the sent email to a specific model for later retrieval in event listeners. It requires the Mail facade and the ability to access message headers.

```php
/**
 * Send an email and do processing on a model with the email
 */
\Mail::send('email.test', [], function ($message) use($email, $subject, $name, $model) {
    $message->from('from@johndoe.com', 'From Name');
    $message->sender('sender@johndoe.com', 'Sender Name');
    $message->to($email, $name);
    $message->subject($subject);

    // Create a custom header that we can later retrieve
    $message->getHeaders()->addTextHeader('X-Model-ID',$model->id);
});
```
Tokens:
Raw