feat: SendGrid subscription_tracking setting (#655)

* Adding in missing `subscription_tracking` setting (#1)

* Adding in missing `subscription_tracking` setting

This adds the capability to send a value for `subscription_tracking` that is included in the `tracking_settings` section of the SendGrid mail body

* code cleanup

* Feature/add bypass unsubscribe management enabled (#2)

* adding new field bypass_unsubscribe_management

---------

Co-authored-by: Warner Onstine <warner.onstine@revelry.co>

Author: warnero

lib/bamboo/adapters/send_grid_adapter.ex

@@ -131,8 +131,10 @@ defmodule Bamboo.SendGridAdapter do
     |> put_settings(config)
     |> put_asm_group_id(email)
     |> put_bypass_list_management(email)
+    |> put_bypass_unsubscribe_management(email)
     |> put_google_analytics(email)
     |> put_click_tracking(email)
+    |> put_subscription_tracking(email)
     |> put_ip_pool_name(email)
     |> put_custom_args(email)
   end
@@ -339,6 +341,18 @@ defmodule Bamboo.SendGridAdapter do
 
   defp put_bypass_list_management(body, _), do: body
 
+  defp put_bypass_unsubscribe_management(body, %Email{private: %{bypass_unsubscribe_management: enabled}})
+       when is_boolean(enabled) do
+    mail_settings =
+      body
+      |> Map.get(:mail_settings, %{})
+      |> Map.put(:bypass_unsubscribe_management, %{enable: enabled})
+
+    Map.put(body, :mail_settings, mail_settings)
+  end
+
+  defp put_bypass_unsubscribe_management(body, _), do: body
+
   defp put_google_analytics(body, %Email{
          private: %{google_analytics_enabled: enabled, google_analytics_utm_params: utm_params}
        }) do
@@ -365,6 +379,17 @@ defmodule Bamboo.SendGridAdapter do
 
   defp put_click_tracking(body, _), do: body
 
+  defp put_subscription_tracking(body, %Email{private: %{subscription_tracking_enabled: enabled}}) do
+    tracking_settings =
+      body
+      |> Map.get(:tracking_settings, %{})
+      |> Map.put(:subscription_tracking, %{enable: enabled, enable_text: enabled})
+
+    Map.put(body, :tracking_settings, tracking_settings)
+  end
+
+  defp put_subscription_tracking(body, _), do: body
+
   defp put_attachments(body, %Email{attachments: []}), do: body
 
   defp put_attachments(body, %Email{attachments: attachments}) do

lib/bamboo/adapters/send_grid_helper.ex

@@ -16,6 +16,7 @@ defmodule Bamboo.SendGridHelper do
   @categories :categories
   @asm_group_id :asm_group_id
   @bypass_list_management :bypass_list_management
+  @bypass_unsubscribe_management :bypass_unsubscribe_management
   @google_analytics_enabled :google_analytics_enabled
   @google_analytics_utm_params :google_analytics_utm_params
   @additional_personalizations :additional_personalizations
@@ -24,6 +25,7 @@ defmodule Bamboo.SendGridHelper do
   @ip_pool_name_field :ip_pool_name
   @custom_args :custom_args
   @click_tracking_enabled :click_tracking_enabled
+  @subscription_tracking_enabled :subscription_tracking_enabled
 
   @doc """
   Specify the template for SendGrid to use for the context of the substitution
@@ -162,6 +164,28 @@ defmodule Bamboo.SendGridHelper do
     raise "expected bypass_list_management parameter to be a boolean, got #{enabled}"
   end
 
+  @doc """
+  Instruct SendGrid to bypass unsubscribe list management for this email.
+
+  If enabled, SendGrid will ignore any email suppression (such as
+  unsubscriptions, bounces, spam filters) for this email. This is useful for
+  emails that all users must receive, such as Terms of Service updates, or
+  password resets.
+
+  ## Example
+
+      email
+      |> with_bypass_unsubscribe_management(true)
+  """
+  def with_bypass_unsubscribe_management(email, enabled) when is_boolean(enabled) do
+    email
+    |> Email.put_private(@bypass_unsubscribe_management, enabled)
+  end
+
+  def with_bypass_unsubscribe_management(_email, enabled) do
+    raise "expected bypass_unsubscribe_management parameter to be a boolean, got #{enabled}"
+  end
+
   @doc """
   Instruct SendGrid to enable or disable Google Analytics tracking, and
   optionally set the UTM parameters for it.
@@ -213,6 +237,27 @@ defmodule Bamboo.SendGridHelper do
     raise "expected with_click_tracking enabled parameter to be a boolean"
   end
 
+  @doc """
+  Instruct SendGrid to enable or disable Subscription Tracking for a particular email.
+
+  Read more about SendGrid click tracking [here](https://docs.sendgrid.com/ui/account-and-settings/tracking#subscription-tracking)
+
+  ## Example
+
+      email
+      |> with_subscription_tracking(true)
+
+      email
+      |> with_subscription_tracking(false)
+  """
+  def with_subscription_tracking(email, enabled)
+      when is_boolean(enabled),
+      do: Email.put_private(email, @subscription_tracking_enabled, enabled)
+
+  def with_subscription_tracking(_email, _enabled) do
+    raise "expected with_subscription_tracking enabled parameter to be a boolean"
+  end
+
   @doc """
   Schedule a time for SendGrid to deliver the email.
 

test/lib/bamboo/adapters/send_grid_adapter_test.exs

@@ -274,6 +274,22 @@ defmodule Bamboo.SendGridAdapterTest do
     assert params["mail_settings"]["bypass_list_management"]["enable"] == true
   end
 
+
+  test "deliver/2 correctly handles a bypass_unsubscribe_management" do
+    email =
+      new_email(
+        from: {"From", "from@foo.com"},
+        subject: "My Subject"
+      )
+
+    email
+    |> Bamboo.SendGridHelper.with_bypass_unsubscribe_management(true)
+    |> SendGridAdapter.deliver(@config)
+
+    assert_receive {:fake_sendgrid, %{params: params}}
+    assert params["mail_settings"]["bypass_unsubscribe_management"]["enable"] == true
+  end
+
   test "deliver/2 correctly handles with_google_analytics that's enabled with no utm_params" do
     email =
       new_email(
@@ -364,6 +380,38 @@ defmodule Bamboo.SendGridAdapterTest do
     assert params["tracking_settings"]["click_tracking"]["enable_text"] == false
   end
 
+  test "deliver/2 correctly handles when with_subscription_tracking is enabled" do
+    email =
+      new_email(
+        from: {"From", "from@foo.com"},
+        subject: "My Subject"
+      )
+
+    email
+    |> Bamboo.SendGridHelper.with_subscription_tracking(true)
+    |> SendGridAdapter.deliver(@config)
+
+    assert_receive {:fake_sendgrid, %{params: params}}
+    assert params["tracking_settings"]["subscription_tracking"]["enable"] == true
+    assert params["tracking_settings"]["subscription_tracking"]["enable_text"] == true
+  end
+
+  test "deliver/2 correctly handles when with_subscription_tracking is disabled" do
+    email =
+      new_email(
+        from: {"From", "from@foo.com"},
+        subject: "My Subject"
+      )
+
+    email
+    |> Bamboo.SendGridHelper.with_subscription_tracking(false)
+    |> SendGridAdapter.deliver(@config)
+
+    assert_receive {:fake_sendgrid, %{params: params}}
+    assert params["tracking_settings"]["subscription_tracking"]["enable"] == false
+    assert params["tracking_settings"]["subscription_tracking"]["enable_text"] == false
+  end
+
   test "deliver/2 correctly handles a sendgrid_send_at timestamp" do
     email =
       new_email(

test/lib/bamboo/adapters/send_grid_helper_test.exs

@@ -149,6 +149,18 @@ defmodule Bamboo.SendGridHelperTest do
     end
   end
 
+
+  test "with_bypass_unsubscribe_management/2 adds the correct property", %{email: email} do
+    email = email |> with_bypass_unsubscribe_management(true)
+    assert email.private[:bypass_unsubscribe_management] == true
+  end
+
+  test "with_bypass_unsubscribe_management/2 raises on non-boolean parameter", %{email: email} do
+    assert_raise RuntimeError, fn ->
+      email |> with_bypass_unsubscribe_management(1)
+    end
+  end
+
   test "with_google_analytics/3 with utm_params", %{email: email} do
     utm_params = %{
       utm_source: "source",
@@ -199,6 +211,24 @@ defmodule Bamboo.SendGridHelperTest do
     end
   end
 
+  test "with_subscription_tracking/2 with enabled set to true", %{email: email} do
+    email = with_subscription_tracking(email, true)
+
+    assert email.private[:subscription_tracking_enabled] == true
+  end
+
+  test "with_subscription_tracking/2 with enabled set false", %{email: email} do
+    email = with_subscription_tracking(email, false)
+
+    assert email.private[:subscription_tracking_enabled] == false
+  end
+
+  test "with_subscription_tracking/2 raises on non-boolean enabled parameter", %{email: email} do
+    assert_raise RuntimeError, fn ->
+      with_subscription_tracking(email, 1)
+    end
+  end
+
   describe "with_send_at/2" do
     test "adds the correct property for a DateTime input", %{email: email} do
       {:ok, datetime, _} = DateTime.from_iso8601("2020-01-31T15:46:00Z")