henryavila/email-tracking

Rastreamento de e-mail Integrado ao Laravel Nova

Version 3.0 Upgrade

This package has been migrated from apps-inteligentes/email-tracking to henryavila/email-tracking The namespace has been moved from AppsInteligentes\EmailTracking to HenryAvila\EmailTracking

To update this package, update your composer.json file to

{
    "require": {
        "henryavila/email-tracking": "^3.0.0"
    }
}

Run a global search a replace on your code looking for AppsInteligentes\EmailTracking and replacing with HenryAvila\EmailTracking

Version 2.0 Upgrade

The version 2 Logs the content of e-mail body. Logs the HTML and TXT content. You can disable this in the config file.

To update this package, update your composer.json file to

{
    "require": {
        "apps-inteligentes/email-tracking": "^2.0.0"
    }
}

and execute

composer update henryavila/email-tracking

Then, publish and run the migrations with:

php artisan vendor:publish --tag="email-tracking-migrations"
php artisan migrate

Mailgun configuration

On mailgun interface, add a webhook to the url APP_URL/webhooks/mailgun

Installation

Setup Laravel Mail with mailgun at https://laravel.com/docs/master/mail#mailgun-driver

Define the environments variable in your .env file

MAIL_MAILER=mailgun
MAILGUN_DOMAIN=yourdomain.com
MAILGUN_SECRET=key-99999999999999999999999999999999

Install the package via composer:

composer require henryavila/email-tracking

Publish and run the migrations with:

php artisan vendor:publish --tag="email-tracking-migrations"
php artisan migrate

Publish the config file with:

php artisan vendor:publish --tag="email-tracking-config"

This is the contents of the published config file:

return [
    /**
     * if defined, the Email model will use this database connection.
     * This connection name must be defined in database.connections config file
     */
    'email-db-connection' => null,

    /**
     * Save the HTML Body of all sent messages
     */
    'log-body-html' => true,

    /**
     * Save the TXT Body of all sent messages
     */
    'log-body-txt' => true,
];

``


Publish the lang files (optional) with:

```bash
php artisan vendor:publish --tag="email-tracking-translations"

Configuration

On NovaServiceProvider.php, add the code:

    /**
     * Get the tools that should be listed in the Nova sidebar.
     *
     * @return array
     */
    public function tools()
    {
        \HenryAvila\EmailTracking\Nova\EmailTrackingTool::make()
    }

This will display the e-mails on Laravel Nova Dashboard.

If you need to customize the Nova Resource, just create a new one extendind HenryAvila\EmailTracking\Nova\EmailResource and use this code

    /**
     * Get the tools that should be listed in the Nova sidebar.
     *
     * @return array
     */
    public function tools()
    {                    
        \HenryAvila\EmailTracking\Nova\EmailTrackingTool::make()
            ->emailResource(CustomEmailResource::class)                        
    }

On all models that can send e-mail, and add the trait ModelWithEmailsSenderTrait

On EventServiceProvider.php, add the code

   /**
     * The event listener mappings for the application.
     *
     * @var array
     */
   protected $listen = [
        \Illuminate\Mail\Events\MessageSent::class => [
            \HenryAvila\EmailTracking\Listeners\LogEmailSentListener::class,
        ],
   ];

At this point, all e-mail sent from app, will be logged on the app, but the sender will not be saved

Save the Email sender

To be able to track the e-mail sender, you must create a custom Mailable or Notification. the default mail can't define the sender (like Nova Reset password e-mail)

Mailable

When creating a new Mailable, overwrite the Base Mailable Class with HenryAvila\EmailTracking\Mail\TrackableMail

This default code:

class SampleMail extends \Illuminate\Mail\Mailable
{
	public function build()
	{
		return $this->view('emails.sample');
	}
}

must be overwritten by this one:

class SampleMail extends \HenryAvila\EmailTracking\Mail\TrackableMail
{
    public function __construct(public \Illuminate\Database\Eloquent\Model $model)
    {
        parent::__construct($model, 'emails.sample');
    }
    
    public function build()
	{
		// Normal build without call to the view() method
	}
}

Basically, remove the view declaration from build() and move it to constructor.

Ps: In this sample, 'emails.sample' is the name of the view generated for this sample. Overwrite it with it with yours.

This new code will pass in the constructor the model that is the email sender. At this point, in build() method, you can continue to setup the mailable, but know that the view is already defined. If you call the view method again, the sender configuration will be overwritten.

To send the Mailable, just pass the model in the mailable constructor

// example: Send the Sample Mail to User with id 1
$user = User::find(1);
Mail::to($user)->send(new App\Mail\SampleMail($user));

Notification

When creating a notification, all you have to do is to change the toMail() method. Replace the default code:

public function toMail($notifiable): MailMessage
{
    return (new MailMessage)
        ->line('The introduction to the notification.')
        ->action('Notification Action', url('/'))
        ->line('Thank you for using our application!');
}

with this code:

public function __construct(public \Illuminate\Database\Eloquent\Model $model)
{
    //
}

public function toMail($notifiable): MailMessage
{
    return (new \HenryAvila\EmailTracking\Notifications\TrackableNotificationMailMessage($this->model))
        ->line('The introduction to the notification.')
        ->action('Notification Action', url('/'))
        ->line('Thank you for using our application!');
}

To send the notification

// User with id 1 send the sample notification to multiple $clientes
$user = User::find(1);
Notification::send($clientes, new SampleNotification($user));

Displaying the e-mails from sender

To be able to display the e-mails sent from a send, add this code in the fields() method on nova resource

public function fields(Request $request)
{
    return [
        ...
        \HenryAvila\EmailTracking\EmailTracking::hasManyEmailsField(),
        ...
    ];
}

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

License

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

Track e-mail delivery with Mailgun Hooks and display the report on Laravel Nova Dashboard