Add ability to bypass list management for SendGridAdapter

lib/bamboo/adapters/send_grid_adapter.ex

@@ -105,6 +105,7 @@ defmodule Bamboo.SendGridAdapter do
     |> put_categories(email)
     |> put_settings(config)
     |> put_asm_group_id(email)
+    |> put_bypass_list_management(email)
   end
 
   defp put_from(body, %Email{from: from}) do
@@ -235,6 +236,21 @@ defmodule Bamboo.SendGridAdapter do
 
   defp put_asm_group_id(body, _), do: body
 
+  defp put_bypass_list_management(body, %Email{private: %{bypass_list_management: enabled}})
+       when is_boolean(enabled) do
+    value = if enabled, do: 1, else: 0
+
+    filters_map =
+      body
+      |> Map.get(:filters, %{})
+      |> Map.put(:bypass_list_management, %{settings: %{enable: value}})
+
+    body
+    |> Map.put(:filters, filters_map)
+  end
+
+  defp put_bypass_list_management(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

@@ -15,6 +15,7 @@ defmodule Bamboo.SendGridHelper do
   @field_name :send_grid_template
   @categories :categories
   @asm_group_id :asm_group_id
+  @bypass_list_management :bypass_list_management
 
   @doc """
   Specify the template for SendGrid to use for the context of the substitution
@@ -135,6 +136,31 @@ defmodule Bamboo.SendGridHelper do
     raise "expected the asm_group_id parameter to be an integer, got #{asm_group_id}"
   end
 
+  @doc """
+  A boolean setting to instruct SendGrid to bypass list management for this
+  email. If enabled, SendGrid will ignore any email supression (such as
+  unsubscriptions, bounces, spam filters) for this email. This is useful for
+  emails that users must receive, such as Terms of Service updates, or
+  password resets.
+
+  More details in the [SendGrid documentation][1].
+
+  [1]: https://sendgrid.com/docs/API_Reference/SMTP_API/apps.html#bypass_list_management)
+
+  ## Example
+
+      email
+      |> with_bypass_list_management(true)
+  """
+  def with_bypass_list_management(email, enabled) when is_boolean(enabled) do
+    email
+    |> Email.put_private(@bypass_list_management, enabled)
+  end
+
+  def with_bypass_list_management(_email, enabled) do
+    raise "expected bypass_list_management parameter to be a boolean, got #{enabled}"
+  end
+
   defp set_template(template, template_id) do
     template
     |> Map.merge(%{template_id: template_id})

test/lib/bamboo/adapters/send_grid_adapter_test.exs

@@ -199,10 +199,11 @@ defmodule Bamboo.SendGridAdapterTest do
   end
 
   test "deliver/2 correctly handles an asm_group_id" do
-    email = new_email(
-      from: {"From", "from@foo.com"},
-      subject: "My Subject",
-    )
+    email =
+      new_email(
+        from: {"From", "from@foo.com"},
+        subject: "My Subject"
+      )
 
     email
     |> Bamboo.SendGridHelper.with_asm_group_id(1234)
@@ -212,6 +213,21 @@ defmodule Bamboo.SendGridAdapterTest do
     assert params["asm"]["group_id"] == 1234
   end
 
+  test "deliver/2 correctly handles a bypass_list_management" do
+    email =
+      new_email(
+        from: {"From", "from@foo.com"},
+        subject: "My Subject"
+      )
+
+    email
+    |> Bamboo.SendGridHelper.with_bypass_list_management(true)
+    |> SendGridAdapter.deliver(@config)
+
+    assert_receive {:fake_sendgrid, %{params: params}}
+    assert params["filters"]["bypass_list_management"]["settings"]["enable"] == 1
+  end
+
   test "deliver/2 doesn't force a subject" do
     email = new_email(from: {"From", "from@foo.com"})
 

test/lib/bamboo/adapters/sendgrid_helper_test.exs → test/lib/bamboo/adapters/send_grid_helper_test.exs

@@ -138,4 +138,15 @@ defmodule Bamboo.SendGridHelperTest do
       email |> with_asm_group_id("1234")
     end
   end
+
+  test "with_bypass_list_management/2 adds the correct property", %{email: email} do
+    email = email |> with_bypass_list_management(true)
+    assert email.private[:bypass_list_management] == true
+  end
+
+  test "with_bypass_list_management/2 raises on non-boolean parameter", %{email: email} do
+    assert_raise RuntimeError, fn ->
+      email |> with_bypass_list_management(1)
+    end
+  end
 end