appletonlearning/laravel-postmark-channel

This package is abandoned and no longer maintained. No replacement package was suggested.

A Postmark channel for Laravel notifications.

v1.0.4 2018-02-19 13:32 UTC

Requires

• php: >=7.0
• illuminate/mail: 5.5.*|5.6.*
• illuminate/notifications: 5.5.*|5.6.*
• illuminate/support: 5.5.*|5.6.*
• wildbit/postmark-php: ^2.5

Requires (Dev)

• mockery/mockery: ^1.0
• phpunit/phpunit: 5.*

MIT

• Adam Campbell

README

Postmark notification channel for Laravel

This adds a Postmark notification channel for Laravel that allows your app to leverage the Postmark API for tracking events related to your emails, like opens, bounces, clicks, etc.

Contents

• Installation
  • Setting up the Postmark service
• Usage
  • Send an email
  • Send a Markdown email
  • Tracking notifications
• Security
• Credits
• License

Installation

Requires PHP 7.0+

$ composer require appletonlearning/laravel-postmark-channel

If using Laravel 5.5+ the package will be auto-discovered.

Setting up the Postmark service

1. Get the API key for your server on Postmark
2. Add the key to your environment config as POSTMARK_KEY

Usage

Send an email

In every Notifiable model you wish to be notifiable via Postmark you must add an email address to that model accessible through a routeNotificationForPostmark method:

class User extends Eloquent
{
    use Notifiable;

    public function routeNotificationForPostmark()
    {
        return $this->email;
    }
}

You may now tell Laravel to send notifications using Postmark in the via method:

use Spur\Postmark\PostmarkChannel;
use Spur\Postmark\PostmarkMessage;

class InvoiceNotification extends Notification
{
    public function via($notifiable)
    {
        return [PostmarkChannel::class];
    }

    public function toPostmark($notifiable)
    {
    	$url = url('/invoice/'.$this->invoice->id);
    
        return (new PostmarkMessage)
            ->greeting('Hello!')
            ->line('One of your invoices has been paid!')
            ->action('View Invoice', $url)
            ->line('Thank you for using our application!');
    }
}

Send a Markdown email

Just like regular mail type notifications, you can also send Markdown emails:

public function toPostmark($notifiable)
{
    $url = url('/invoice/'.$this->invoice->id);

    return (new PostmarkMessage)
        ->subject('Invoice Paid')
        ->markdown('mail.invoice.paid', ['url' => $url]);
}

In fact, the Postmark channel has the same API as the built-in Laravel mail channel. Follow the Laravel Mail Notifications and Markdown Mail Notifications documentation for full options.

Tracking notifications

One of the benefits of using the Postmark channel over the default mail channel is that allows for event tracking, such as deliveries, clicks, opens, and bounces on sent emails. To track email events you must first store each notification in your database, which must at least have a column to track the email's Postmark-specific MessageID.

To capture the ID on send we listen to Laravel's Illuminate\Notifications\Events\NotificationSent event. Register a listener for this event in your EventServiceProvider:

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Notifications\Events\NotificationSent' => [
        'App\Listeners\LogNotification',
    ],
];

As the Laravel documentation states:

Within an event listener, you may access the notifiable, notification, and channel properties on the event to learn more about the notification recipient or the notification itself...

/**
 * Handle the event.
 *
 * @param  NotificationSent  $event
 * @return void
 */
public function handle(NotificationSent $event)
{
    // $event->channel
    // $event->notifiable
    // $event->notification
    // $event->response
}

With Postmark, the $event->response object contains the ID, status, and other data sent back from Postmark when the email has been sent through their system:

{
    "To": "[e-mail]",
    "SubmittedAt": "2014-02-17T07:25:01.4178645-05:00",
    "MessageID": "0a129aee-e1cd-480d-b08d-4f48548ff48d",
    "ErrorCode": 0,
    "Message": "OK"
}

Once your emails are being successfully stored with Postmark's MessageID it becomes very easy to track all events that occur with each email using the Postmark Webhooks API.

Testing

$ composer test

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Adam Campbell
• All Contributors

License

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