====== Mailgun ======

---- plugin ----

Description: This plugin sends email through Mailgun using its API. This is for phplist 3.3.1 and later.
Author: Duncan Cameron
Compatible: 3.3.1

Source repo: https://github.com/bramley/phplist-plugin-mailgun

----

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

The plugin also provides a webhook to receive bounce notifications from Mailgun. The subscriber identified in a bounce notification will be marked as blacklisted, with records added to the event log and to the subscriber's history.

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.

===== Installation =====

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

===== Configuration =====



==== Settings page ====

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

{{:plugin:mailgun_1.png?nolink&400|}}

The base URL can be changed to ''%%https://api.eu.mailgun.net%%'' if you are sending from the EU region.

Within your Mailgun account copy the Private API key and HTTP webhook signing key from the API Security page accessed through Settings in the left-side menu.
<WRAP center round box 60%>

{{:plugin:mailgun_2.png?nolink&250|}}
</WRAP>


Enter the Sending Domain that you used when setting-up Mailgun and then had Mailgun verify it.

<WRAP center round box 60%>
{{:plugin:mailgun_3.png?nolink&500|}}
</WRAP>


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

On the Webhooks page, menu Sending > Webhooks from the Mailgun Dashboard, add a webhook:

**Event type**: Permanent Failure

**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=Mailgun&secret=xxxxxxx</code>

You should first test the URL using the Test Webhook fields and button. Verify that the plugin has received and processed the request by reviewing the Event Log. There should be an entry for a "failed" event.
{{ :plugin:mailgun_4.png?nolink&500 |}}

Then add the webhook using the Add Webhook button on the right-side of the Webhooks page.

When the webhook has been added Mailgun will send notifications of hard bounces (permanent failures). The plugin will mark the subscriber as blacklisted, add a record to the event log, and add a record to the subscriber history.
==== 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 Mailgun.

====== Support ======
Please raise any questions or problems in the user forum https://discuss.phplist.org/