Disable all emails setting

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### Unreleased
 
+* Add new configuration option named `send_emails` which can be used to disable the sending of all current and future emails.
+ This option can be set to a boolean value or a proc/lambda that returns a boolean value. - @cjilbert504
+
 ### 6.4.0
 
 * Introduce `:pay` load hook - @excid3

docs/2_configuration.md

@@ -78,14 +78,18 @@ bin/rails generate pay:email_views
 
 ## Emails
 
-Emails can be enabled/disabled independently using the `emails` configuration option as show in the configuration section below (all are enabled by default).
+Emails can be enabled/disabled as a whole by using the `send_emails` configuration option or independently by 
+using the `emails` configuration option as shown in the configuration section below (all emails are enabled by default).
 
 When enabled, the following emails will be sent when:
 
+- A payment action is required
+- A payment failed
 - A charge succeeded
 - A charge was refunded
 - A yearly subscription is about to renew
-- A payment action is required
+- A subscription trial is about to end
+- A subscription trial has ended
 
 ## Configuration
 
@@ -106,6 +110,10 @@ Pay.setup do |config|
  config.routes_path = "/pay" # Only when automount_routes is true
  # All processors are enabled by default. If a processor is already implemented in your application, you can omit it from this list and the processor will not be set up through the Pay gem.
  config.enabled_processors = [:stripe, :braintree, :paddle]
+
+ # To disable all emails, set the following configuration option to false:
+ config.send_emails = true
+
  # All emails can be configured independently as to whether to be sent or not. The values can be set to true, false or a custom lambda to set up more involved logic. The Pay defaults are show below and can be modified as needed.
  config.emails.payment_action_required = true
  config.emails.payment_failed = true

docs/7_webhooks.md

@@ -58,17 +58,36 @@ Since we support multiple payment providers, each event type is prefixed with th
 To add your own webhook listener, you can simply subscribe to the event type.
 
 ```ruby
+# app/webhooks/my_charge_succeeded_processor.rb
 class MyChargeSucceededProcessor
  def call(event)
  # do your processing here
  end
 end
 
+# config/initializers/pay.rb
 ActiveSupport.on_load(:pay) do
  Pay::Webhooks.delegator.subscribe "stripe.charge.succeeded", MyChargeSucceededProcessor.new
 end
 ```
 
+If you are sending emails from your custom webhook handlers, be sure to use the [`Pay.send_email?` method](https://github.com/pay-rails/pay/blob/c067771d8c7514acde4b948b474caf054bb0e25d/lib/pay.rb#L113)
+in a conditional check to ensure that you don't send any emails if they are disabled either individually or as a whole.
+For example:
+
+```ruby
+# app/webhooks/my_charge_succeeded_processor.rb
+class MyChargeSucceededProcessor
+ def call(event)
+ pay_charge = Pay::Stripe::Charge.sync(event.data.object.id, stripe_account: event.try(:account))
+
+ if pay_charge && Pay.send_email?(:receipt, pay_charge) # <---- Note the usage of the `send_email?` method here
+ Pay.mailer.with(pay_customer: pay_charge.customer, pay_charge: pay_charge).receipt.deliver_later
+ end
+ end
+end
+```
+
 ### Unsubscribing from a webhook listener
 
 Need to unsubscribe or disable one of the default webhook processors? Simply unsubscribe from the event name:

lib/pay.rb

@@ -57,6 +57,9 @@ def self.support_email=(value)
  mattr_accessor :enabled_processors
  @@enabled_processors = [:stripe, :braintree, :paddle]
 
+ mattr_accessor :send_emails
+ @@send_emails = true
+
  mattr_accessor :emails
  @@emails = ActiveSupport::OrderedOptions.new
  @@emails.payment_action_required = true
@@ -111,12 +114,19 @@ def self.setup
  end
 
  def self.send_email?(email_option, *remaining_args)
- config_option = emails.send(email_option)
+ if resolve_option(send_emails, *remaining_args)
+ email_config_option_enabled = emails.send(email_option)
+ resolve_option(email_config_option_enabled, *remaining_args)
+ else
+ false
+ end
+ end
 
- if config_option.respond_to?(:call)
- config_option.call(*remaining_args)
+ def self.resolve_option(option, *remaining_args)
+ if option.respond_to?(:call)
+ option.call(*remaining_args)
  else
- config_option
+ option
  end
  end
 end

test/pay_test.rb

@@ -101,6 +101,42 @@ class Pay::Test < ActiveSupport::TestCase
  Pay.enabled_processors = original
  end
 
+ test "can disable all emails with a boolean" do
+ original_send_email_value = Pay.send_emails
+
+ Pay.emails.keys.each do |mail_action|
+ Pay.emails.stub mail_action, true do
+ assert Pay.send_email?(mail_action)
+ end
+ end
+
+ Pay.send_emails = false
+
+ Pay.emails.keys.each do |mail_action|
+ refute Pay.send_email?(mail_action)
+ end
+ ensure
+ Pay.send_emails = original_send_email_value
+ end
+
+ test "can disable all emails with a lambda" do
+ original_send_email_value = Pay.send_emails
+
+ Pay.emails.keys.each do |mail_action|
+ Pay.emails.stub mail_action, true do
+ assert Pay.send_email?(mail_action)
+ end
+ end
+
+ Pay.send_emails = -> { false }
+
+ Pay.emails.keys.each do |mail_action|
+ refute Pay.send_email?(mail_action)
+ end
+ ensure
+ Pay.send_emails = original_send_email_value
+ end
+
  test "can configure email options with a boolean" do
  Pay.emails.stub :subscription_renewing, true do
  assert Pay.send_email?(:subscription_renewing)