Add support for SendGrid's asm_group_id (#457)

This is useful for letting recipients unsubscribe from certain types of email communication. By assigning an ASM group id to the email, hitting "Unsubscribe" in the footer will unsubscribe the recipient only from this email group, not all communication.

lib/bamboo/adapters/send_grid_adapter.ex

@@ -104,6 +104,7 @@ defmodule Bamboo.SendGridAdapter do
     |> put_attachments(email)
     |> put_categories(email)
     |> put_settings(config)
+    |> put_asm_group_id(email)
   end
 
   defp put_from(body, %Email{from: from}) do
@@ -197,8 +198,7 @@ defmodule Bamboo.SendGridAdapter do
   end
 
   defp put_template_substitutions(body, _), do: body
-
-
+
   defp put_dynamic_template_data(body, %Email{
          private: %{send_grid_template: %{dynamic_template_data: dynamic_template_data}}
        }) do
@@ -227,6 +227,14 @@ defmodule Bamboo.SendGridAdapter do
 
   defp put_categories(body, _), do: body
 
+  defp put_asm_group_id(body, %Email{private: %{asm_group_id: asm_group_id}})
+       when is_integer(asm_group_id) do
+    body
+    |> Map.put(:asm, %{group_id: asm_group_id})
+  end
+
+  defp put_asm_group_id(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

@@ -14,6 +14,7 @@ defmodule Bamboo.SendGridHelper do
 
   @field_name :send_grid_template
   @categories :categories
+  @asm_group_id :asm_group_id
 
   @doc """
   Specify the template for SendGrid to use for the context of the substitution
@@ -116,6 +117,24 @@ defmodule Bamboo.SendGridHelper do
   def add_dynamic_field(_email, field, _value),
     do: raise("expected the name parameter to be of type binary or atom, got #{field}")
 
+  @doc """
+  An integer id for an ASM (Advanced Suppression Manager) group that this email should belong to.
+  This can be used to let recipients unsubscribe from only a certain type of communication.
+
+  ## Example
+
+      email
+      |> with_asm_group_id(1234)
+  """
+  def with_asm_group_id(email, asm_group_id) when is_integer(asm_group_id) do
+    email
+    |> Email.put_private(@asm_group_id, asm_group_id)
+  end
+
+  def with_asm_group_id(_email, asm_group_id) do
+    raise "expected the asm_group_id parameter to be an integer, got #{asm_group_id}"
+  end
+
   defp set_template(template, template_id) do
     template
     |> Map.merge(%{template_id: template_id})

test/lib/bamboo/adapters/send_grid_adapter_test.exs

@@ -198,6 +198,20 @@ defmodule Bamboo.SendGridAdapterTest do
     assert personalization["substitutions"] == %{"%foo%" => "bar"}
   end
 
+  test "deliver/2 correctly handles an asm_group_id" do
+    email = new_email(
+      from: {"From", "from@foo.com"},
+      subject: "My Subject",
+    )
+
+    email
+    |> Bamboo.SendGridHelper.with_asm_group_id(1234)
+    |> SendGridAdapter.deliver(@config)
+
+    assert_receive {:fake_sendgrid, %{params: params}}
+    assert params["asm"]["group_id"] == 1234
+  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

@@ -127,4 +127,15 @@ defmodule Bamboo.SendGridHelperTest do
 
     assert length(email.private[:categories]) == 10
   end
+
+  test "with_asm_group_id/2 adds the correct property", %{email: email} do
+    email = email |> with_asm_group_id(1234)
+    assert email.private[:asm_group_id] == 1234
+  end
+
+  test "with_asm_group_id/2 raises on non-integer id", %{email: email} do
+    assert_raise RuntimeError, fn ->
+      email |> with_asm_group_id("1234")
+    end
+  end
 end