====== Send Grid ======

---- plugin ----

description: This plugin sends email through SendGrid using its API. This is for phplist 3.1.1 and later.
author     : Duncan Cameron
compatible : 3.3.1+

sourcerepo : https://github.com/bramley/phplist-plugin-sendgrid

----

This plugin sends email through the SendGrid API. Once you have enabled the plugin then phplist will send all emails, campaigns and system emails, using the plugin.

To revert to using either the php mail() function or an SMTP server, as specified in the config.php file, you should disable the plugin.

The plugin also includes a webhook that can be used to handle bounce notifications from SendGrid.
===== Installation =====

See the README file on the GitHub page https://github.com/bramley/phplist-plugin-sendgrid for how to install the plugin.

===== Configuration =====



==== Settings page ====

When you have enabled the plugin there will be a SendGrid group on the Settings page where you can configure the plugin.

  *     The API key. You must generate an API Key in your SendGrid account and enter the value here.

{{:plugin:sendgrid1.png?nolink&500|}}

==== Send rate ====

The plugin does not handle the sending rate, which is done by core phplist as for any other method of sending emails. You should set the throttle, batch size, etc to meet any limit set by SendGrid.

===== Errors when sending =====

If the call to the SendGrid API fails then an event is added, which you can see on the Event Log page.
As an example, this is the event reported when the API key is invalid

{{:plugin:sendgrid2.png?nolink&600|}}

===== Using the webhook to process bounces =====

On the SendGrid dashboard, select Settings > Mail Settings from the left-hand navigation menu, then select Event Webhook

**Authorisation Method:** None

**HTTP Post URL:** similar to the following URL but adjusted for your domain and path to phplist. The secret parameter is the "Secret for remote processing" on the phplist Settings page

<code>https://mysite.com/lists/admin/?page=webhook&pi=SendGridPlugin&secret=xxxxxxx</code>

**Events to be POSTed to your URL:** check Dropped, Bounced, Unsubscribed and Spam Reports.

You should test the URL using the **Test Integration** button. SendGrid will send a request containing several events for the email address ''example@test.com''. Because that email address does not exist in your phplist database the events will all be for an unknown subscriber.

There should be a entry in the Event Log page showing 11 unknown (email address is not recognised).

{{:plugin:sendgrid3.png?nolink&700|}}

If you add that email address to phplist then repeat the **Test Integration** the new event log entry should show one bounce, one spam report, one dropped, and one unsubscribe, and 7 unhandled (not one of the events that the webhook handles).

{{:plugin:sendgrid4.png?nolink&700|}}

Then enable the webhook using the **Event Webhook Status**.

SendGrid will now send notifications for each of the selected events. For each event the plugin will mark the subscriber as blacklisted and add a record to the subscriber history.
====== Support ======
Please raise any questions or problems in the user forum https://discuss.phplist.org/