Merge pull request #65 from SparkPost/FAD-3598

Transactional

Author: rajumsys

admin.widget.class.php

@@ -132,6 +132,7 @@ public function admin_page_init()
         add_settings_field('password', 'API Key*', array($this, 'render_password_field'), 'sp-options', 'general');
         add_settings_field('enable_tracking', 'Enable tracking*', array($this, 'render_enable_tracking_field'), 'sp-options', 'general');
         add_settings_field('template', 'Template', array($this, 'render_template_field'), 'sp-options', 'general');
+        add_settings_field('transactional', 'Transactional', array($this, 'render_transactional_field'), 'sp-options', 'general');
 
         add_settings_section('overrides', 'Overrides', null, 'sp-overrides');
         add_settings_field('from_name', 'From name', array($this, 'render_from_name_field'), 'sp-overrides', 'overrides');
@@ -199,8 +200,14 @@ public function sanitize($input)
             $new_input['enable_tracking'] = true;
         } else {
             $new_input['enable_tracking'] = false;
+        }
 
+        if(!empty($input['transactional'])) {
+          $new_input['transactional'] = true;
+        } else {
+          $new_input['transactional'] = false;
         }
+
         return $new_input;
     }
 
@@ -296,4 +303,12 @@ public function render_enable_debugging_field()
     {
         echo '<label><input type="checkbox" id="enable_debugging" name="enable_debugging" value="1" checked />Show email debugging messages</label>';
     }
+
+      public function render_transactional_field()
+      {
+          printf('<label><input type="checkbox" id="transactional" name="sp_settings[transactional]" value="1" %s />Mark emails as transactional</label>
+          <br/><small>Upon checked, by default, it\'ll set mark all emails as transactional. It should be set false (using hooks) for non-transactional emails.</small>',
+           $this->settings['transactional'] ? 'checked' : '');
+
+      }
 }

docs/hooks.md

@@ -27,3 +27,4 @@ Hook names are prefixed with `wpsp_`.
 | wpsp_reply_to                | Filter   |
 | wpsp_body_headers            | Filter   |   
 | wpsp_smtp_msys_api           | Filter   |
+| wpsp_transactional           | Filter   | Set whether an email is transactional or not. 

docs/transactional.md

@@ -0,0 +1,31 @@
+
+# Transactional setting
+
+## Background
+As of v2.5.0 (TODO: Fix version number before release), wordpress-sparkpost introduced [Transactional](https://www.sparkpost.com/blog/transactional-email-vs-mass-email) support for emails.
+
+Emails created by WordPress are, generally, transactional in nature. Those are user registration, password reset emails etc. So, we wanted to set that flag on by default. Non-transactional emails are generated by third party plugins. In such case, that plugin should mark it as non-transactional. Because this option supports hook, it's easy to programmatically flip the value. We'll have an example below.
+
+Also because this is quite a breaking change, we won't just change this value for the existing installations. Any current installations of this plugin upgraded to new version will have this unchecked by default.
+
+## New Installations
+For new installations, Transactional will be enabled by default. In plugin's settings page, it'll be checked on. If you want to disable it, just uncheck and save the settings.
+
+## Upgrades
+If you are upgrading to this new version from an existing installation, it won't be enabled by default. You must go to plugin's setting page and enable it from there.
+
+## Programmatically modifying transactional setting
+If you know that you're sending a non-transactional email, you can set it to false before sending using a filter and then remove the filter after you sent the email. Here is an example:
+
+```php
+function unsetTransactional() {
+  return false;
+};
+
+add_filter('wpsp_transactional', 'unsetTransactional');
+
+// now send your email using wp_mail function
+
+// as sending is done, let's remove the filter so other emails are not affected
+remove_filter('wpsp_transactional', 'unsetTransactional');
+```

mailer.http.class.php

@@ -82,7 +82,8 @@ protected function get_request_body()
         // enable engagement tracking
         $body['options'] = array(
             'open_tracking' => (bool) apply_filters('wpsp_open_tracking', $tracking_enabled),
-            'click_tracking' => (bool) apply_filters('wpsp_click_tracking', $tracking_enabled)
+            'click_tracking' => (bool) apply_filters('wpsp_click_tracking', $tracking_enabled),
+            'transactional' => (bool) apply_filters('wpsp_transactional', $this->settings['transactional'])
         );
 
         // pass through either stored template or inline content

mailer.smtp.class.php

@@ -26,7 +26,8 @@ public function configure_phpmailer($phpmailer) {
         $x_msys_api = array(
             'options' => array (
                 'open_tracking' => (bool) apply_filters('wpsp_open_tracking', $tracking_enabled),
-                'click_tracking' => (bool) apply_filters('wpsp_click_tracking', $tracking_enabled)
+                'click_tracking' => (bool) apply_filters('wpsp_click_tracking', $tracking_enabled),
+                'transactional' => (bool) apply_filters('wpsp_transactional', $settings['transactional'])
             )
         );
 

sparkpost.class.php

@@ -17,7 +17,8 @@ class SparkPost
         'from_email' => '',
         'enable_sparkpost' => false,
         'enable_tracking' => true,
-        'template' => ''
+        'template' => '',
+        'transactional' => false
     );
 
     var $settings;
@@ -39,7 +40,9 @@ public function __construct()
 
     public function sp_activate()
     {
-        update_option('sp_settings', self::$settings_default);
+      $settings = self::$settings_default;
+      $settings['transactional'] = true; // setting it here to apply this default value to new installation only as this is breaking change
+      update_option('sp_settings', $settings);
     }
 
     public function sp_deactivate()