From 1cc4620b994f72f8be5a3768e718b1946e706446 Mon Sep 17 00:00:00 2001 From: Pierre-Luc Auclair Date: Sun, 28 Feb 2016 01:30:15 -0500 Subject: [PATCH] 0.2 release -- Batch - Fix behavior of the to() method to conform with default PW behaviour - Simple batch mode implementation - Shorthand sending has been tested and should be working -- please send feedback! - Email open and click tracking - Updated documentation --- README.md | 16 ++++++- WireMailMailgun.module | 99 +++++++++++++++++++++++++++++++++++++-- WireMailMailgunConfig.php | 14 ++++++ todo.md | 8 +++- 4 files changed, 130 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index e56f707..7cd0d91 100755 --- a/README.md +++ b/README.md @@ -28,4 +28,18 @@ Basic usage is as such: **$WireMailMailgun->setDomainName( *string* $domainName )** -**$WireMailMailgun->setTestMode( *bool* $bool )** \ No newline at end of file +**$WireMailMailgun->setTestMode( *bool* $bool )** + +**$WireMailMailgun->setBatchMode( *bool* $bool )** + +When batch mode is set to **true** (default mode of operation), each recipient passed to the `to()` method will not be able to see who else is receiving the sent email. This will send one email per "To:" recipient. + +Set to **false** to disable this behavior. This will send one email with multiple "To:" recipients. + +Note that in both cases all CCs and BCCs will be delivered for **each email sent**. This means that if batch mode is on, that you have 10 "To:" recipients and 3 CCs, 40 emails will be sent in total. + +**Important**: Mailgun has a maximum hard limit of recipients allowed per batch of 1,000. [Read more about batch sending.](https://documentation.mailgun.com/user_manual.html#batch-sending) + +**$WireMailMailgun->setClickTracking( *bool* $bool )** + +**$WireMailMailgun->setOpenTracking( *bool* $bool )** \ No newline at end of file diff --git a/WireMailMailgun.module b/WireMailMailgun.module index 9f4e94f..7f719af 100755 --- a/WireMailMailgun.module +++ b/WireMailMailgun.module @@ -5,18 +5,20 @@ * * @property string apiKey The API key set in config * @property string domain The domain for the API key + * @property bool batchMode True by default. See setBatchMode() method of this class for more info. */ class WireMailMailgun extends WireMail implements Module, ConfigurableModule { private $apiUrl = 'https://api.mailgun.net/v3/'; + private $batchMode = true; public static function getModuleInfo() { return array( 'title' => 'Wire Mail Mailgun', - 'version' => '0.1', - 'summary' => "Extends WireMail through the Mailgun API", - 'href' => 'http://mailgun.com/', + 'version' => '0.2', + 'summary' => "Mailgun for ProcessWire", + 'href' => 'https://github.com/plauclair/WireMailMailgun', 'author' => 'plauclair', 'singular' => false, 'autoload' => false @@ -37,14 +39,22 @@ class WireMailMailgun extends WireMail implements Module, ConfigurableModule 'o:testmode' => $this->isTestMode(), ]; + // Batch mode variables + if ($this->batchMode === true) { + $postFields['recipient-variables'] = $this->getToRecipientsVariables(); + } + + // Set CC recipients if ($this->getCCRecipients() !== false) { $postFields['cc'] = $this->getCCRecipients(); } + // Set BCC recipients if ($this->getBCCRecipients() !== false) { $postFields['bcc'] = $this->getBCCRecipients(); } + // Set body if (!empty($this->mail['bodyHTML'])) { $postFields['html'] = $this->mail['bodyHTML']; // TODO: Replace the next line with something that @@ -54,6 +64,19 @@ class WireMailMailgun extends WireMail implements Module, ConfigurableModule $postFields['text'] = $this->mail['body']; } + // Email Open Tracking + if ($this->clickTracking() === true) { + $postFields['o:tracking-clicks'] = 'yes'; + } + + // Email Click tracking + if ($this->openTracking() === true) { + $postFields['o:tracking-opens'] = 'yes'; + } + + // Headers + $postFields['h:X-Mailer'] = $this->mail['header']['X-Mailer']; + $options = array( CURLOPT_USERPWD => "api:{$this->apiKey}", CURLOPT_URL => "{$this->apiUrl}{$this->domain}/messages", @@ -61,7 +84,6 @@ class WireMailMailgun extends WireMail implements Module, ConfigurableModule CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_POSTFIELDS => $postFields, - CURLOPT_HTTPHEADER => ['X-Mailer' => $this->mail['header']['X-Mailer']], CURLOPT_SSL_VERIFYPEER => $this->sslCheck(), ); @@ -206,6 +228,48 @@ class WireMailMailgun extends WireMail implements Module, ConfigurableModule return (!empty($to)) ? implode(',', $to) : false; } + /** + * Get the recipient variables + * + * For now, this is used to emulate the default to() + * method behavior. Mailgun hard limit on this calling + * style is 1000 recipients per request + */ + private function getToRecipientsVariables() + { + $recipients = $this->mail['toName']; + $recipientsVariables = []; + + $i = 1; + foreach ($recipients as $email => $name) { + $recipientsVariables[$email] = ['id' => $i, 'name' => $name]; + $i += 1; + } + + return json_encode($recipientsVariables); + } + + /** + * Enables or disables batch mode + * + * This is on by default, meaning that all emails in the To field won't see the other recipients. + */ + public function setBatchMode($bool) + { + if (is_bool($bool)) { + $this->batchMode = $bool; + } + } + + /** + * Will allow merging an array of emails with + * their recipients variables + */ + public function mergeToRecipientsVariables() + { + // THIS IS A STUB + } + /** * Set the email CC address * @@ -382,4 +446,31 @@ class WireMailMailgun extends WireMail implements Module, ConfigurableModule return "ProcessWire domain}>"; } } + + public function setClickTracking($bool) + { + if ($bool === true) { + $this->trackClicks = 'trackClicks'; + } else if ($bool === false) { + $this->trackClicks = null; + } + } + + private function clickTracking() + { + return ($this->trackClicks == 'trackClicks') ? true : false; + } + + public function setOpenTracking($bool) + { + if ($bool === true) { + $this->trackOpens = 'trackOpens'; + } else if ($bool === false) { + $this->trackOpens = null; + } + } + + private function openTracking() { + return ($this->trackOpens == 'trackOpens') ? true : false; + } } \ No newline at end of file diff --git a/WireMailMailgunConfig.php b/WireMailMailgunConfig.php index c0b2306..f03b71d 100644 --- a/WireMailMailgunConfig.php +++ b/WireMailMailgunConfig.php @@ -37,6 +37,20 @@ function __construct() { 'type' => 'Text', 'columnWidth' => 50 ), + array( + 'name' => 'trackOpens', + 'label' => __('Track Message Opens'), + 'type' => 'Checkbox', + 'value' => 'trackOpens', + 'columnWidth' => 50 + ), + array( + 'name' => 'trackClicks', + 'label' => __('Track Message Clicks'), + 'type' => 'Checkbox', + 'value' => 'trackClicks', + 'columnWidth' => 50 + ), array( 'name' => 'testMode', 'label' => __('Enable Test Mode'), diff --git a/todo.md b/todo.md index 7b64e31..2ac004b 100755 --- a/todo.md +++ b/todo.md @@ -9,8 +9,9 @@ - to, cc, bcc support // DONE ### 0.2 -- Shorthand wireMail($args) usage -- tracking clicks and opens per email +- Shorthand wireMail($args) usage // OK +- tracking clicks and opens per email // DONE +- Batch mode // OK ### 0.3 - o:tag @@ -28,3 +29,6 @@ - Remove user from list - List sync - Send to list `$mail->toList('name'); $mail->send()` + +### 0.7 +- Mailgun mail validation https://documentation.mailgun.com/api-email-validation.html \ No newline at end of file