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

@@ -28,4 +28,18 @@ Basic usage is as such:
 
 **$WireMailMailgun->setDomainName( *string* $domainName )**
 
-**$WireMailMailgun->setTestMode( *bool* $bool )**
+**$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 )**

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,14 +64,26 @@ 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",
 			CURLOPT_HEADER => false,
 			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 <processwire@{$this->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;
+	}
 }

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'),

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