Merge pull request #7 from nswdpc/cherrypick-from-taggable

Improvements from tagging work

README.md

@@ -4,19 +4,24 @@ This module provides functionality to send emails via the Mailgun API and store
 
 ## Requirements
 
+See [composer.json](./composer.json)
+
 + silverstripe/framework ^4
 + Symbiote's [Queued Jobs](https://github.com/symbiote/silverstripe-queuedjobs) module
-+ Mailgun PHP SDK ^3 and its recommended dependencies
++ Mailgun PHP SDK ^3, kriswallsmith/buzz, nyholm/psr7
+
+### Mailgun configuration
 
-and...
+You need:
 
 * A Mailgun account
-* At least one non-sandbox Mailgun mailing domain ([verified is best](http://mailgun-documentation.readthedocs.io/en/latest/quickstart-sending.html#verify-your-domain)) in your choice of region
+* At least one non-sandbox Mailgun mailing domain ([verified is best](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain)) in your choice of region
 * A Mailgun API key or a [Mailgun Domain Sending Key](https://www.mailgun.com/blog/mailgun-ip-pools-domain-keys) for the relevant mailing domain (the latter is recommended)
+* MailgunEmail and MailgunMailer are configured in your project (see below)
 
 ## Installing
 
-```
+```shell
 composer require nswdpc/silverstripe-mailgun-sync
 ```
 
@@ -26,11 +31,13 @@ composer require nswdpc/silverstripe-mailgun-sync
 
 Configuration of your Mailgun domain and account is beyond the scope of this document but is straightforward.
 
-The best starting point is [Verifying a Domain](http://mailgun-documentation.readthedocs.io/en/latest/quickstart-sending.html#verify-your-domain).
+You should verify your domain to avoid message delivery issues. The best starting point is [Verifying a Domain](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain). 
+
+MXToolBox.com is a useful tool to check your mailing domain has valid DMARC records.
 
 ### Module
 
-Add the following to your project's YML config:
+Add the following to your project's yaml config:
 ```yml
 ---
 Name: local-mailgunsync-config
@@ -65,8 +72,10 @@ NSWDPC\Messaging\Mailgun\Connector\Base:
   # the previous one, to allow variable rotation
   webhook_previous_filter_variable: ''
 ---
+# Configure the mailer
 Name: local-mailer
 After:
+  # Override core email configuration
   - '#emailconfig'
 ---
 # Send messages via the MailgunMailer
@@ -77,9 +86,9 @@ SilverStripe\Core\Injector\Injector:
     class: 'NSWDPC\Messaging\Mailgun\MailgunMailer'
 ```
 
-> Remember to flush configuration after a YML change.
+> Remember to flush configuration after a configuration change.
 
-See [Detailed Configuration](./docs/en/005-detailed_configuration.md)
+See [detailed configuration, including project tags](./docs/en/005-detailed_configuration.md)
 
 ## Sending
 
@@ -177,6 +186,10 @@ See the [Mailgun PHP SDK documentation](https://github.com/mailgun/mailgun-php)
 
 ## Queued Jobs
 
+The module uses the [Queued Jobs](https://github.com/symbiote/silverstripe-queuedjobs) module to deliver email at a later time.
+
+This way, a website request that involves delivering an email will not be held up by API issues.
+
 ### SendJob
 
 This is a queued job that can be used to send emails depending on the ```send_via_job``` config value -
@@ -186,11 +199,11 @@ This is a queued job that can be used to send emails depending on the ```send_vi
 
 Messages are handed off to this queued job, which is configured to send after one minute. Once delivered, the message parameters are cleared to reduce space used by large messages.
 
-This job is marked as 'broken' immediately upon an API or other general error.
+This job is marked as 'broken' immediately upon an API or other general error. Please read the Queued Jobs Health Check documentation to get assistance with Broken job reporting.
 
 ### TruncateJob
 
-Use this job to clear out older MailgunEvent webhook records.
+Use this job to clear out older MailgunEvent webhook records. If you don't use webhooks to store events, this job can remain unused.
 
 ### RequeueJob
 
@@ -206,7 +219,7 @@ On the next queue run, these jobs will attempt to send again.
 
 ## Manual Resubmission
 
-Messages can be resent from the Mailgun control panel
+Messages can be resent from the Mailgun control panel. This depends on your Message Retention setting for the relevant mailing domain in Mailgun.
 
 ## DMARC considerations
 
@@ -221,11 +234,14 @@ See [dmarc.org](https://dmarc.org) for more information on the importance of DMA
 
 ## Tests
 
-See ./tests
+Unit tests: [./tests](./tests). Tests use the [TestMessage](./tests/TestMessage.php) connector.
+
+### Sending emails using sandbox/testmode
 
-When testing this module, you probably want to avoid emails going out to the internet.
+For acceptance testing, you can use a combination of the Mailgun sandbox domain and API testmode.
 
-Ensure you use a Mailgun sandbox domain with approved recipients to avoid this.
++ Sandbox domain: set the `api_domain` value in configuration to the sandbox domain provided by Mailgun. Remember to list approved recipients in the sandbox domain settings in the Mailgun control panel.
++ Test mode: set the `api_testmode` value to true. In testmode, Mailgun accepts but does not deliver messages.
 
 ## Breaking changes in 1.0 release
 
@@ -244,3 +260,23 @@ Synchronisation of events is now handled by the [webhooks controller](./docs/en/
 BSD-3-Clause
 
 See [LICENSE](./LICENSE.md)
+
+## Maintainers
+
++ [dpcdigital@NSWDPC:~$](https://dpc.nsw.gov.au)
+
+## Bugtracker
+
+We welcome bug reports, pull requests and feature requests on the Github Issue tracker for this project.
+
+Please review the [code of conduct](./code-of-conduct.md) prior to opening a new issue.
+
+## Security
+
+If you have found a security issue with this module, please email digital[@]dpc.nsw.gov.au in the first instance, detailing your findings.
+
+## Development and contribution
+
+If you would like to make contributions to the module please ensure you raise a pull request and discuss with the module maintainers.
+
+Please review the [code of conduct](./code-of-conduct.md) prior to completing a pull request.

_config/config.yml

@@ -18,7 +18,7 @@ NSWDPC\Messaging\Mailgun\Connector\Base:
   send_via_job : 'when-attachments'
   default_recipient : ''
 # Mailer config
-NSWDPC\Messaging\Mailgun\Mailer:
+NSWDPC\Messaging\Mailgun\MailgunMailer:
    always_from: ''
 ---
 Name: mailgunsyncqueue

composer.json

@@ -21,6 +21,16 @@
     "support" : {
         "issues" : "https://github.com/nswdpc/silverstripe-mailgun-sync/issues"
     },
+    "autoload": {
+        "psr-4": {
+            "NSWDPC\\Messaging\\Mailgun\\Tests\\": [
+                "tests/"
+            ],
+            "NSWDPC\\Messaging\\Mailgun\\": [
+                "src/"
+            ]
+        }
+    },
     "require": {
         "symbiote/silverstripe-queuedjobs": "^4.5",
         "mailgun/mailgun-php": "^3",

docs/en/001-index.md

@@ -8,50 +8,61 @@
 
 MailgunEmail extends Email and provides added features for use with Mailgun via `setCustomParameters`
 
-These extra options, variables, headers and recipient variables are passed to the Mailgun API
+These extra options, variables, headers and recipient variables are passed to the Mailgun API.
 
 ```php
 use SilverStripe\Control\Email\Email;
 
-$email = Email::create();
-
-// add standard email to, cc etc
-
-// add custom params for Mailgun:
-
-$variables = [
-    'test' => 'true',
-    'foo' => 'bar',
-];
-
-$options = [
-    'testmode' => 'yes',
-    'tag' => ['tag1','tag2','tag4'],
-    'tracking' => 'yes', // test tracking turn on
-    'require-tls' => 'yes'
+$person = get_person();
+
+// Set parameters (no need to prefix keys)
+$parameters = [
+
+    // Set v: prefixed variables
+    'variables' => [
+        'test' => 'true',
+        'foo' => 'bar',
+    ],
+
+    // Set o: prefixed options
+    'options' => [
+        'deliverytime' => $person->getReminderTime(\DateTimeInterface::RFC2822),
+        'dkim' => 'yes',// require DKIM for this specific message
+        'tag' => ['tag1','tag2','tag4'], // send some tags for analytics
+        'tracking' => 'yes', // turn tracking on just for this message
+        'require-tls' => 'yes', // require a TLS connection when Mailgun connects to the remote mail server
+        'skip-verification' => 'no' // do not skip TLS verification
+    ],
+
+    // h: prefixed headers
+    'headers' => [
+        'X-Test-Header' => 'testing'
+    ],
+
+    // Specific recipient variables
+    'recipient_variables' => [
+        $person->Email => ["tagline" => "Reminder"]
+    ]
 ];
 
-$headers = [
-    'X-Test-Header' => 'testing'
-];
+// Send the email
+$email = Email::create();
+$email->setTo($person->Email)
+    ->setSubject('A reminder')
+    ->setFrom('[email protected]')
+    ->setCustomParameters($parameters)
+    ->send();
+```
 
-$recipient_variables = [
-    $to_address => ["unique_id" => "testing_123"]
-];
+## Tagging
 
-$email->setCustomParameters([
-    'options' => $options,
-    'variables' => $variables,
-    'headers' => $headers,
-    'recipient-variables' => $recipient_variables
-]);
+To set tags on a message, include them in the `$parameters['options']['tag']` array.
 
-$email->send();
-```
+[Mailgun places a limit of 3 tags per message](https://documentation.mailgun.com/en/latest/user_manual.html#tagging).
 
 ## Future delivery
 
-To send in the future, use [scheduled delivery](https://documentation.mailgun.com/en/latest/user_manual.html#scheduling-delivery)
+To send in the future, use [scheduled delivery](https://documentation.mailgun.com/en/latest/user_manual.html#scheduling-delivery) with an RFC2822 formatted datetime.
 
 ```php
 //send in the future example

docs/en/005-detailed_configuration.md

@@ -2,6 +2,12 @@
 
 More detailed configuration information is as follows
 
+```yml
+NSWDPC\Messaging\Mailgun\Connector\Base:
+  api_domain: ''
+  ...
+```
+
 ### api_domain
 
 This is your custom mailing domain. It's recommended that your verify this in DNS
@@ -44,6 +50,13 @@ Mailgun requires a 'to' parameter. If your system sends messages with Bcc/Cc but
 
 ### always_from
 
+> This setting will be replaced with `Email.send_all_emails_from` in the future. You can use that instead, now.
+
+```yml
+NSWDPC\Messaging\Mailgun\MailgunMailer:
+   always_from: ''
+```
+
 If you wish to have all emails sent from a single address by default, regardless of the From header set then add the relevant value here.
 This is off by default but can come in handy if your application is sending emails from random addresses, which will cause you to fall foul of DMARC rules.
 

src/Connector/Base.php

@@ -168,7 +168,7 @@ final protected function sendViaJob()
     }
 
     /**
-     * When true, the Sender header is always set to the From value. When false, use {@link NSWDPC\Messaging\Mailgun\Mailer::setSender()} to set the Sender header as required
+     * When true, the Sender header is always set to the From value. When false, use {@link NSWDPC\Messaging\Mailgun\MailgunMailer::setSender()} to set the Sender header as required
      */
     final protected function alwaysSetSender()
     {

src/Connector/Message.php

@@ -82,14 +82,13 @@ public function getMime(MailgunEvent $event)
     /**
      * Send a message with parameters
      * See: http://mailgun-documentation.readthedocs.io/en/latest/api-sending.html#sending
-     * @returns SendResponse
+     * @return SendResponse|QueuedJobDescriptor|null
      * @param array $parameters an array of parameters for the Mailgun API
      * @param string $in a strtotime value added to 'now' being the time that the message will be sent via a queued job, if enabled
      */
     public function send($parameters)
     {
-        $client = $this->getClient();
-        $domain = $this->getApiDomain();
+
         // If configured and not already specified, set the Sender hader
         if ($this->alwaysSetSender() && !empty($parameters['from']) && empty($parameters['h:Sender'])) {
             $parameters['h:Sender'] = $parameters['from'];
@@ -116,6 +115,26 @@ public function send($parameters)
             $parameters["v:wfv"] = $variable;
         }
 
+        // Send a message defined by the parameters provided
+        return $this->sendMessage($parameters);
+
+    }
+
+    /**
+     * Sends a message
+     * @param array $parameters
+     */
+    protected function sendMessage(array $parameters) {
+
+        /**
+         * @var Mailgun\Mailgun
+         */
+        $client = $this->getClient();
+        /**
+         * @var string
+         */
+        $domain = $this->getApiDomain();
+
         // send options
         $send_via_job = $this->sendViaJob();
         $in = $this->getSendIn();// seconds