synergitech / laravel-postal

This library integrates Postal with the standard Laravel mail framework.

Laravel Postal

This library integrates Postal with the standard Laravel mail framework.

Install

First, install the package using Composer:

composer require synergitech/laravel-postal

Next, run the package migrations:

php artisan migrate

Next, add your credentials to your .env and set your mail driver to postal:

MAIL_MAILER=postal

POSTAL_DOMAIN=https://your.postal.server
POSTAL_KEY=yourapicredential

Finally, add postal as a mailer to your config/mail.php file

'mailers' => [
    'postal' => [
        'transport' => 'postal',
    ],
],

If you want to alter the configuration further, you can reference the config/postal.php file for the keys to place in your environment. Alternatively, you can publish the config file in the usual way if you wish to make specific changes:

php artisan vendor:publish --provider="SynergiTech\Postal\PostalServiceProvider"

Also make sure you have filled out who the email comes from and that the domain you use is authorised by the API credential.

[email protected]
MAIL_FROM_NAME="Your Company"

Usage

As this is a driver for the main Laravel Mail framework, sending emails is the same as usual - just follow the Laravel Mail documentation - however we recommend you make use of the PostalNotificationChannel class to enable full email tracking within your software.

Upgrading

Upgrading to V4

Version 4 only supports Laravel 9 and newer owing to significant changes in how Laravel processes email.

We also now throw TransportException when an API error occurs, instead of a BadMethodCallException.

Upgrading to V3

If you are updating to Laravel 7 as well, you will need to update your environment variable names.

Upgrading from V1 to V2

Please note version 2 is backwards compatible with version 1 as long as you are not using a listener. Version 2 is also configured differently and includes many more features (including support for webhooks) so if you're upgrading from version 1, please take time to re-read this information.

Upgrading between V2 and V2.1

There are no backwards incompatible changes between these two versions unless you have customized the default table names. Prior to v2.1, we published our migration files into your application. Beginning in v2.1, we now present these to Laravel in our service provider.

Our migrations will be run again when upgrading between these two versions. The migrations will not recreate the table or otherwise error when it detects the presence of the default tables. However, if they have been renamed, they will be created again. Simply create a new migration to drop the tables.

Logging messages sent against notifiable models

Create an email notification as you would normally but have 'SynergiTech\Postal\PostalNotificationChannel' or PostalNotificationChannel::class returned in the via() method.

In order to associate the messages with the notifiable model, you will need to return the model object in a method called logEmailAgainstModel in your notification class. If you do not include this method, the messages will still be logged (if you have that enabled in the config) but the link back to your notifiable model will not be created.

Here is a complete example of what you need to do to ensure your notifiable model is linked to the emails that get sent.

use App\Notifications\EnquiryNotification;
use Illuminate\Support\Facades\Notification;
use SynergiTech\Postal\PostalNotificationChannel;

// Using the Notifiable trait
$user->notify(new EnquiryNotification($enquiry));

// On demand notifications
Notification::route(PostalNotificationChannel::class, '[email protected]')
    ->notify(new EnquiryNotification($enquiry));

namespace App\Notifications;

use Illuminate\Notifications\Notification;
use SynergiTech\Postal\PostalNotificationChannel;

class EnquiryNotification extends Notification
{
    private $enquiry;

    public function __construct($enquiry)
    {
        $this->enquiry = $enquiry;
    }

    public function via($notifiable)
    {
        return [PostalNotificationChannel::class];
    }

    public function logEmailAgainstModel()
    {
        return $this->enquiry;
    }

    public function toMail($notifiable)
    {
        // message constructed here
    }
}

You can still send messages through Postal as a driver if you just leave 'mail' in the via() method but the channel from this package is responsible for creating the link so if you do not use PostalNotificationChannel as mentioned above, there will not be a link between the messages and your notifiable model.

Please note that Postals PHP client can throw exceptions if it fails to submit the message to the server (i.e. a permission problem occurred or an email address wasn't valid) so if you have a process which relies on sending an email, it would be advisable to send the notification before proceeding (i.e. saving the updated object to the database).

Send all email to one address (i.e. for development)

Our similar package for FuelPHP allows you to send all messages to a specific email address defined in your environment. Laravel already has a mechanism for this and you can use it by updating the config/mail.php file as follows:

$config = [
    // existing config array
];

if (getenv('EMAIL')) {
    $config['to'] = [
        'address' => getenv('EMAIL'),
        'name' => 'Your Name'
    ];
}

return $config;

Webhooks

This package also provides the ability for you to record webhooks from Postal. This functionality is enabled by default.

Verifying the webhook signature

Each webhook payload should include a couple of unique values for some level of accuracy in your webhooks but if you want to verify the signature, you must provide the signing key from your Postal and enable this feature.

You can access the signing public key by running postal default-dkim-record on your Postal server and copying the value of the p parameter (excluding the semicolon) to your environment under the key POSTAL_WEBHOOK_PUBLIC_KEY.

Listeners

As with default Laravel, you can make use of the Illuminate\Mail\Events\MessageSent listener. In version 1, you received the whole response from Postal however in version 2 you will only receive a Postal-Message-ID and this is contained in the message header. This will allow you to access the emails created as this will be the value of the postal_email_id column.

The change allows your code to meet static analysis requirements.

namespace App\Listeners;

use Illuminate\Mail\Events\MessageSent;

class MessageSentListener
{
    /**
     * Handle the event.
     *
     * @param MessageSent $event
     * @return void
     */
    public function handle(MessageSent $event)
    {
        $headers = $event->message->getHeaders();
        $postalmessageid = $headers->get('postal-message-id')?->getBodyAsString();

        if ($postalmessageid) {
            // do something here
        }
    }
}

Running tests

To run the full suite of unit tests:

vendor/bin/phpunit -c phpunit.xml

You will need xdebug installed to generate code coverage.

Docker

A sample Dockerfile is provided to setup an environment to run the tests without configuring your local machine. The Dockerfile can test multiple combinations of versions for PHP and Laravel via arguments.

docker build . --build-arg PHP_VERSION=8.1 --build-arg LARAVEL=9

laravel-postal's Issues

PHP 8 support

Please add PHP 8 support, test for incompatibilities and update composer.json.

composer update 
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires synergitech/laravel-postal ^3.1 -> satisfiable by synergitech/laravel-postal[v3.1.0].
    - synergitech/laravel-postal v3.1.0 requires php ^7.3 -> your php version (8.0.0) does not satisfy that requirement.

Add a trait for hasEmails

This means we don't have to change multiple models if the class changes

Morphmany Through

If an email relates to multiple models, such as a job related to a client that also has a contact, there needs to be a way to have it be clear that this email relates to all these entities.

A solution for this could be to have a 'emailLinks' table of sorts, that would have multiple rows all with the same email id, with the related model.

One can then just reference this relation, which then references the email relation accordingly.

Headers are not passed to Postal Message

Hey,
maybe I setup something wrong, but with the logEmailAgainstModel method set and the 'postal.enable.emaillogging' value set to true I do not get the notifiable_class and notifiable_id headers passed to Postal.

On inspection they do get set on the underlying Swift_Message instance, but get lost during the transformation to a Postal message. If I understood the code correctly the swiftToPostal method of the PostalTransportClass simply does not set any custom headers.

This does not only break the email logging feature, but also does not allow the application to pass any additional headers, which could break some workflows.

Feature: Allow to set the tag attribute on Postal messages

Postal allows to tag messages send via their API. This would be a useful feature to add to this package.

Laravel 9 Support

Composer install fails for laravel-postal with Laravel 9. Laravel 9 is released as stable since February 8th, 2022.

composer update                                                                                         
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - synergitech/laravel-postal[v3.3.0, ..., v3.3.2] require laravel/framework ^6.0|7.0|^8.0 -> found laravel/framework[v6.0.0, ..., 6.x-dev, v7.0.0, v8.0.0, ..., 8.x-dev] but it conflicts with your root composer.json require (^9.0).
    - Root composer.json requires synergitech/laravel-postal ^3.3 -> satisfiable by synergitech/laravel-postal[v3.3.0, v3.3.1, v3.3.2].

Use the option --with-all-dependencies (-W) to allow upgrades, downgrades and removals for packages currently locked to specific versions.

Laravel 9 support might need some changes to this library as the new switched from SwiftMailer to SymfonyMailer which similar but requires some minor changes (see https://laravel.com/docs/9.x/upgrade#symfony-mailer)

Transport is broken in laravel 7

In Laravel 7 the TransportManager was removed in favor of the new MailManager.
This breaks transport because postal isn't registered.
This can be fixed by using the MailManager instead of the TransportManager in the PostalServiceProvider.

v2 breaks due to missing `updated_at` column

Hey,
first thank you for your packet.

Sadly when I was evaluating it I ran into the following error:
Illuminate\Database\QueryException: SQLSTATE[42703]: Undefined column: 7 ERROR: column "updated_at" of relation "emails" does not exist.

The error occurs from https://github.com/SynergiTech/laravel-postal/blob/master/src/PostalTransport.php#L198 where the save method on the Email model is called which tries to set the updated_at timestamp.

To prevent this issue it should be enough to add const UPDATED_AT = null; to the Email model to tell Laravel to not use the updated_at field.

PHP 8 release

Do you mind tagging a new release to support PHP 8 officially?

Thanks for the great package!

V2: Verify postal webhook signature

we should add functionality to verify the X-Postal-Signature webhook header

php 8.1 support