swiftmade / laravel-sendgrid-notification-channel
Laravel Notification Channel for Sengrid.com
Fund package maintenance!
swiftmade
Installs: 152 993
Dependents: 0
Suggesters: 0
Security: 0
Stars: 25
Watchers: 7
Forks: 6
Open Issues: 0
Requires
- php: >=7.2
- illuminate/notifications: ^7.0|^8.0|^9.0|^10.0|^11.0
- illuminate/support: ^7.0|^8.0|^9.0|^10.0|^11.0
- sendgrid/sendgrid: ^7.11|^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.8
- mockery/mockery: ^1.5
- orchestra/testbench: ^5.0|^6.0|^7.0|^8.0|^9.0
- phpunit/phpunit: ^8.4|^9.0|^10.0
README
Allows you to send Laravel notifications using Sendgrid's Dynamic Transactional Templates feature.
- Minimum Laravel version required: 7.x
- Minimum PHP version required: 7.2
(For older versions of Laravel, install v1)
Contents
Installation
To get started, you need to require this package:
composer require swiftmade/laravel-sendgrid-notification-channel
The service provider will be auto-detected by Laravel. If you've turned auto-discovery off, add the following service provider in your config/app.php
.
NotificationChannels\SendGrid\SendGridServiceProvider::class,
Next, make sure you have a valid Sendgrid API key in config/services.php
. You may copy the example configuration below to get started:
return [ // other services... // add this... 'sendgrid' => [ 'api_key' => env('SENDGRID_API_KEY'), ], ];
Usage
To send an email using dynamic templates, you need to:
- Return
SendGridChannel::class
in thevia()
method. (Notmail
) - Add and implement the
toSendGrid($notifiable){ }
method.
Example:
<?php namespace App\Notifications; use Illuminate\Notifications\Notification; use NotificationChannels\SendGrid\SendGridChannel; class ExampleNotification extends Notification { public function via($notifiable) { return [ SendGridChannel::class, // And any other channels you want can go here... ]; } // ... public function toSendGrid($notifiable) { return (new SendGridMessage('Your SendGrid template ID')) /** * optionally set the from address. * by default this comes from config/mail.from * ->from('no-reply@test.com', 'App name') */ /** * optionally set the recipient. * by default it's $notifiable->routeNotificationFor('mail') * ->to('hello@example.com', 'Mr. Smith') */ ->payload([ "template_var_1" => "template_value_1" ]); } }
toSendGrid
method will receive a $notifiable
entity and should return a NotificationChannels\SendGrid\SendGridMessage
instance.
💡 Unless you set it explicitly, the From address will be set to config('mail.from.address')
and the To value will be what returns from $notifiable->routeNotificationFor('mail');
Sandbox Mode
The sandbox mode is off by default. You can use the setSandboxMode($bool)
method to enable/disable it.
Example:
return (new SendGridMessage('Your SendGrid template ID')) ->setSandboxMode(true) ->payload([ 'template_var_1' => 'template_value_1', 'template_var_2' => [ 'value_1', 'value_2', 'value_3', ], ]);
When making a request with sandbox mode enabled, Sendgrid will validate the form, type, and shape of your request. No email will be sent. You can read more about the sandbox mode here.
Attachments
You can attach or embed (inline attachment) files to your messages. SendGridMessage
object exposes the following methods to help you do that:
attach($file, $options)
attachData($data, $name, $options)
embed($file, $options)
embedData($data, $name, $options)
Good to know:
- While using
attachData
andembedData
you must always pass themime
key in the options array. - You can use the
as
key in the options to change the filename to appears in the email. (e.g.attach($file, ['as' => 'invoice-3252.pdf'])
) embed
andembedData
methods will return the ContentID withcid:
in front (e.g.embed('avatar.jpg') -> "cid:avatar.jpg"
).
Full Access to the Sendgrid Mail Object
If you need more customization options, you can work directly with the underlying Sendgrid Mail object.
To utilize this, simply pass a callback using the customize
method.
use SendGrid\Mail\Mail; return (new SendGridMessage('Your SendGrid template ID')) ->payload([ 'template_var_1' => 'template_value_1', 'template_var_2' => [ 'value_1', 'value_2', 'value_3', ], ]) ->customize(function (Mail $mail) { // Send a carbon copy (cc) to another address $mail->addCc('test@test.com'); // Send a blind carbon copy (bcc) to another address $mail->addBcc('bcc@test.com'); });
For all the options, you can see Sendgrid's Mail class here.
Accessing SendGrid Response
After the notification is sent, Laravel will emit Illuminate\Notifications\Events\NotificationSent
event. You can listen to this event to get the SendGrid response object and/or message ID.
use Illuminate\Notifications\Events\NotificationSent; Event::listen(NotificationSent::class, function (NotificationSent $event) { /** * @var \SendGrid\Response $response */ $response = $event->response; });
Changelog
Please see CHANGELOG for more information what has changed recently.
Testing
$ composer test
Security
If you discover any security related issues, please email hello@swiftmade.co instead of using the issue tracker.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.