PHPackages monovm/laravel-postal - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. monovm/laravel-postal ActiveLibrary[Mail & Notifications](/categories/mail) monovm/laravel-postal ===================== This library integrates Postal with the standard Laravel mail framework. v5.0.3(1mo ago)0160MITPHPPHP ^8.0 Since Jan 4Pushed 1mo agoCompare [ Source](https://github.com/monovm/laravel-postal)[ Packagist](https://packagist.org/packages/monovm/laravel-postal)[ Docs](https://github.com/monovm/laravel-postal)[ RSS](/packages/monovm-laravel-postal/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)Dependencies (10)Versions (5)Used By (0) Laravel Postal ============== [](#laravel-postal) [![Latest Stable Version](https://camo.githubusercontent.com/ed2317f5135bb9e0108696434b4da88bde4506bf73aa49233f0854cbc9bfb955/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73796e65726769746563682f6c61726176656c2d706f7374616c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/synergitech/laravel-postal)[![Tests](https://github.com/SynergiTech/laravel-postal/workflows/Tests/badge.svg)](https://github.com/SynergiTech/laravel-postal/workflows/Tests/badge.svg) This library integrates [Postal](https://github.com/postalhq/postal) with the standard Laravel mail framework. Install ------- [](#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. ``` MAIL_FROM_ADDRESS=noreply@your.company MAIL_FROM_NAME="Your Company" ``` Usage ----- [](#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) ### Upgrading to V4 [](#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 [](#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 [](#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 [](#upgrading-between-v2-and-v21) 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 [](#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, 'john.smith@example.com') ->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) [](#send-all-email-to-one-address-ie-for-development) Our [similar package for FuelPHP](https://github.com/SynergiTech/fuelphp-postal) 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 -------- [](#webhooks) This package also provides the ability for you to record webhooks from Postal. This functionality is enabled by default. ### Verifying the webhook signature [](#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 --------- [](#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 ------------- [](#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 [](#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 ``` ### Health Score 42 — FairBetter than 90% of packages Maintenance93 Actively maintained with recent releases Popularity11 Limited adoption so far Community13 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~151 days Total 4 Last Release 37d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f5c284a2bc7a21425bf7fa4a51d46e05d2244a1f3afcab40e9e9d31d8481aae5?d=identicon)[monovm](/maintainers/monovm) --- Top Contributors [![willpower232](https://avatars.githubusercontent.com/u/1619102?v=4)](https://github.com/willpower232 "willpower232 (46 commits)")[![Josh-G](https://avatars.githubusercontent.com/u/487384?v=4)](https://github.com/Josh-G "Josh-G (43 commits)")[![behzadsp](https://avatars.githubusercontent.com/u/58994682?v=4)](https://github.com/behzadsp "behzadsp (5 commits)")[![forestlovewood](https://avatars.githubusercontent.com/u/22885049?v=4)](https://github.com/forestlovewood "forestlovewood (3 commits)")[![SiebeVE](https://avatars.githubusercontent.com/u/14889418?v=4)](https://github.com/SiebeVE "SiebeVE (3 commits)")[![lrakauskas](https://avatars.githubusercontent.com/u/42625423?v=4)](https://github.com/lrakauskas "lrakauskas (1 commits)")[![morganarnel](https://avatars.githubusercontent.com/u/84181964?v=4)](https://github.com/morganarnel "morganarnel (1 commits)")[![dependabot-preview[bot]](https://avatars.githubusercontent.com/in/2141?v=4)](https://github.com/dependabot-preview[bot] "dependabot-preview[bot] (1 commits)") --- Tags laravelpostalemail ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/monovm-laravel-postal/health.svg) ``` [![Health](https://phpackages.com/badges/monovm-laravel-postal/health.svg)](https://phpackages.com/packages/monovm-laravel-postal) ``` ### Alternatives [synergitech/laravel-postal This library integrates Postal with the standard Laravel mail framework. 38107.1k](/packages/synergitech-laravel-postal)[rdanusha/laravel-elastic-email Package for send emails with attachments via elastic email driver 1114.5k](/packages/rdanusha-laravel-elastic-email)[signaturetech/laravel-otp A package to generate and manage otp 181.2k](/packages/signaturetech-laravel-otp) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)