├── .gitignore
├── README.md
├── _config.yml
├── composer.json
├── config
└── mail-tracker.php
├── migrations
├── 2016_03_01_193027_create_sent_emails_table.php
├── 2016_09_07_193027_create_sent_emails_Url_Clicked_table.php
└── 2016_11_10_213551_add-message-id-to-sent-emails-table.php
└── src
├── Events
├── EmailSentEvent.php
├── LinkClickedEvent.php
├── PermanentBouncedMessageEvent.php
└── ViewEmailEvent.php
├── Facades
└── MailTracker.php
├── MailTracker.php
├── MailTrackerController.php
├── MailTrackerServiceProvider.php
├── Model
├── SentEmail.php
└── SentEmailUrlClicked.php
└── SNSController.php
/.gitignore:
--------------------------------------------------------------------------------
1 | /vendor
2 | .idea
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # MailTracker
2 |
3 | MailTracker will hook into all outgoing emails from Laravel and inject a tracking code into it. It will also store the rendered email in the database. There is also an interface to view sent emails.
4 |
5 | ## NOTE: For Laravel < 5.3.23
6 |
7 | ## Install (Laravel)
8 |
9 | Via Composer
10 |
11 | ``` bash
12 | $ composer require jeylabs/mail-tracker
13 | ```
14 |
15 | Add the following to the providers array in config/app.php:
16 |
17 | ``` php
18 | Jeylabs\MailTracker\MailTrackerServiceProvider::class,
19 | ```
20 |
21 | Publish the config file and migration
22 | ``` bash
23 | $ php artisan vendor:publish
24 | ```
25 |
26 | Run the migration
27 | ``` bash
28 | $ php artisan migrate
29 | ```
30 |
31 | ## Usage
32 |
33 | Once installed, all outgoing mail will be logged to the database. The following config options are available in config/mail-tracker.php:
34 |
35 | * **track-open**: set to true to inject a tracking pixel into all outgoing html emails.
36 | * **track-click**: set to true to rewrite all anchor href links 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.
37 | * **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 to never purge old emails from the database.
38 | * **route**: The route information for the tracking URLs. Set the prefix and middlware as desired.
39 | * **date-format**: You can define the format to show dates in the Admin Panel.
40 |
41 | ## Events
42 |
43 | When an email is sent, viewed, or a link is clicked, its tracking information is counted in the database using the Jeylabs\MailTracker\Model\SentEmail model. You may want to do additional processing on these events, so an event is fired in these cases:
44 |
45 | * Jeylabs\MailTracker\Events\EmailSentEvent
46 | * Jeylabs\MailTracker\Events\ViewEmailEvent
47 | * Jeylabs\MailTracker\Events\LinkClickedEvent
48 |
49 | 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.
50 |
51 | * Jeylabs\MailTracker\Events\PermanentBouncedMessageEvent
52 |
53 | To install an event listener, you will want to create a file like the following:
54 |
55 | ``` php
56 | sent_email...
83 | }
84 | }
85 | ```
86 |
87 | ``` php
88 | email_address...
115 | }
116 | }
117 | ```
118 |
119 | Then you must register the event in your \App\Providers\EventServiceProvider $listen array:
120 |
121 | ``` php
122 | /**
123 | * The event listener mappings for the application.
124 | *
125 | * @var array
126 | */
127 | protected $listen = [
128 | 'Jeylabs\MailTracker\Events\ViewEmailEvent' => [
129 | 'App\Listeners\EmailViewed',
130 | ],
131 | 'Jeylabs\MailTracker\Events\PermanentBouncedMessageEvent' => [
132 | 'App\Listeners\BouncedEmail',
133 | ],
134 | ];
135 | ```
136 |
137 | ### Passing data to the event listeners
138 |
139 | Often times you may need to link a sent email to another model. The best way to handle this is to add a header to your outgoing email that you can retrieve in your event listener. Here is an example:
140 |
141 | ``` php
142 | /**
143 | * Send an email and do processing on a model with the email
144 | */
145 | \Mail::send('email.test', [], function ($message) use($email, $subject, $name, $model) {
146 | $message->from('info@jeylabs.com', 'From Name');
147 | $message->sender('info@jeylabs.com', 'Sender Name');
148 | $message->to($email, $name);
149 | $message->subject($subject);
150 |
151 | // Create a custom header that we can later retrieve
152 | $message->getHeaders()->addTextHeader('X-Model-ID',$model->id);
153 | });
154 | ```
155 |
156 | and then in your event listener:
157 |
158 | ```
159 | public function handle(EmailSentEvent $event)
160 | {
161 | $tracker = $event->sent_email;
162 | $model_id = $event->getHeader('X-Model-ID');
163 | $model = Model::find($model_id);
164 | // Perform your tracking/linking tasks on $model knowing the SentEmail object
165 | }
166 | ```
167 |
168 | Note that the headers you are attaching to the email are actually going out with the message, so do not store any data that you wouldn't want to expose to your email recipients.
169 |
170 | ## Amazon SES features
171 |
172 | If you use Amazon SES, you can add some additional information to your tracking. To set up the SES callbacks, first set up SES notifications under your domain in the SES control panel. Then subscribe to the topic by going to the admin panel of the notification topic and creating a subscription for the URL you copied from the admin page. The system should immediately respond to the subscription request. If you like, you can use multiple subscriptions (i.e. one for delivery, one for bounces). See above for events that are fired on a failed message.
173 |
--------------------------------------------------------------------------------
/_config.yml:
--------------------------------------------------------------------------------
1 | theme: jekyll-theme-cayman
--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "jeylabs/mail-tracker",
3 | "description": "MailTracker will hook into all outgoing emails from Laravel and inject a tracking code into it. It will also store the rendered email in the database. There is also an interface to view sent emails.",
4 | "keywords": ["jeylabs", "laravel", "mail-tracker"],
5 | "license": "MIT",
6 | "type": "Package",
7 | "authors": [
8 | {
9 | "name": "jeylabs",
10 | "email": "ratheep.ceymplon@jeylabs.com",
11 | "homepage": "https://jeylabs.com",
12 | "role": "Developer"
13 | }
14 | ],
15 | "require": {
16 | "laravel/framework": ">=5.3.23",
17 | "guzzlehttp/guzzle": "^5.3.1|^6.2.1",
18 | "illuminate/support": "~5.1",
19 | "aws/aws-sdk-php-laravel": "~3.0",
20 | "aws/aws-php-sns-message-validator": "^1.1",
21 | "php" : "~5.5|~7.0"
22 | },
23 |
24 | "autoload": {
25 | "psr-4": {
26 | "Jeylabs\\MailTracker\\": "src"
27 | }
28 | },
29 | "minimum-stability": "stable",
30 | "prefer-stable": true
31 | }
32 |
--------------------------------------------------------------------------------
/config/mail-tracker.php:
--------------------------------------------------------------------------------
1 | true,
4 | 'track-click' => true,
5 | 'expire-days' => 60,
6 | 'emails-per-page' => 30,
7 | 'date-format' => 'm/d/Y g:i a',
8 | 'route' => [
9 | 'prefix' => 'mail-track',
10 | 'middleware' => ['web'],
11 | ],
12 | 'custom-inject' => false,
13 | 'custom-inject-html' => ''
14 | ];
--------------------------------------------------------------------------------
/migrations/2016_03_01_193027_create_sent_emails_table.php:
--------------------------------------------------------------------------------
1 | increments('id');
17 | $table->char('hash',32)->unique();
18 | $table->text('headers');
19 | $table->string('sender');
20 | $table->string('recipient');
21 | $table->string('subject');
22 | $table->integer('opens');
23 | $table->integer('clicks');
24 | $table->timestamps();
25 | });
26 | }
27 |
28 | /**
29 | * Reverse the migrations.
30 | *
31 | * @return void
32 | */
33 | public function down()
34 | {
35 | Schema::drop('sent_emails');
36 | }
37 | }
38 |
--------------------------------------------------------------------------------
/migrations/2016_09_07_193027_create_sent_emails_Url_Clicked_table.php:
--------------------------------------------------------------------------------
1 | increments('id');
17 | $table->integer('sent_email_id')->unsigned();
18 | $table->foreign('sent_email_id')->references('id')->on('sent_emails')->onDelete('cascade');
19 | $table->string('url');
20 | $table->char('hash',32);
21 | $table->integer('clicks')->default('1');
22 | $table->timestamps();
23 | });
24 | }
25 |
26 | /**
27 | * Reverse the migrations.
28 | *
29 | * @return void
30 | */
31 | public function down()
32 | {
33 | Schema::drop('sent_emails_url_clicked');
34 | }
35 | }
36 |
--------------------------------------------------------------------------------
/migrations/2016_11_10_213551_add-message-id-to-sent-emails-table.php:
--------------------------------------------------------------------------------
1 | string('message_id')->nullable()->unique();
18 | $table->text('meta');
19 | });
20 | }
21 |
22 | /**
23 | * Reverse the migrations.
24 | *
25 | * @return void
26 | */
27 | public function down()
28 | {
29 | Schema::table('sent_emails', function(Blueprint $table) {
30 | $table->dropColumn('message_id');
31 | $table->dropColumn('meta');
32 | });
33 | }
34 | }
35 |
--------------------------------------------------------------------------------
/src/Events/EmailSentEvent.php:
--------------------------------------------------------------------------------
1 | sent_email = $sent_email;
23 | }
24 | }
--------------------------------------------------------------------------------
/src/Events/LinkClickedEvent.php:
--------------------------------------------------------------------------------
1 | sent_email = $sent_email;
23 | }
24 | }
--------------------------------------------------------------------------------
/src/Events/PermanentBouncedMessageEvent.php:
--------------------------------------------------------------------------------
1 | email_address = $email_address;
22 | }
23 | }
--------------------------------------------------------------------------------
/src/Events/ViewEmailEvent.php:
--------------------------------------------------------------------------------
1 | sent_email = $sent_email;
22 | }
23 | }
--------------------------------------------------------------------------------
/src/Facades/MailTracker.php:
--------------------------------------------------------------------------------
1 | getMessage();
20 |
21 | // Create the trackers
22 | $this->createTrackers($message);
23 |
24 | // Purge old records
25 | $this->purgeOldRecords();
26 | }
27 |
28 | public function sendPerformed(\Swift_Events_SendEvent $event)
29 | {
30 | // If this was sent through SES, retrieve the data
31 | if(config('mail.driver') == 'ses') {
32 | $message = $event->getMessage();
33 | $this->updateSesMessageId($message);
34 | }
35 | }
36 |
37 | protected function updateSesMessageId($message)
38 | {
39 | // Get the SentEmail object
40 | $headers = $message->getHeaders();
41 | $hash = $headers->get('X-Mailer-Hash')->getFieldBody();
42 | $sent_email = SentEmail::where('hash',$hash)->first();
43 |
44 | // Get info about the
45 | $sent_email->message_id = $headers->get('X-SES-Message-ID')->getFieldBody();
46 | $sent_email->save();
47 | }
48 |
49 | protected function addTrackers($html, $hash)
50 | {
51 | if(config('mail-tracker.track-open')) {
52 | $html = $this->injectTrackingPixel($html, $hash);
53 | }
54 | if(config('mail-tracker.track-click')) {
55 | $html = $this->injectLinkTracker($html, $hash);
56 | }
57 | if (config('mail-tracker.custom-inject')){
58 | $customInject = config('mail-tracker.custom-inject-html');
59 | $html = $this->customInject($html, $customInject);
60 | }
61 | return $html;
62 | }
63 |
64 | protected function injectTrackingPixel($html, $hash)
65 | {
66 | // Append the tracking url
67 | $tracking_pixel = '';
68 |
69 | $linebreak = str_random(32);
70 | $html = str_replace("\n",$linebreak,$html);
71 |
72 | if(preg_match("/^(.*