Adds support for enabling sendgrid click tracking (beam-community#618)

Resolve beam-community#596 

Adds support for enabling click_tracking for sendgrid emails. 
The commit sets both `enabled` and `enabled_text` for HTML 
and text-only emails. 

Consider Sendgrid's message for click tracking: 

> It's important to consider the privacy implications of enabling Click and Open tracking before enabling the feature. Depending on the country where your recipient resides, using this feature to track engagement may require the unambiguous consent of the recipient.

References: 

https://docs.sendgrid.com/ui/account-and-settings/tracking
https://docs.sendgrid.com/api-reference/settings-tracking/update-click-tracking-settings

lib/bamboo/adapters/send_grid_adapter.ex

@@ -129,6 +129,7 @@ defmodule Bamboo.SendGridAdapter do
  |> put_asm_group_id(email)
  |> put_bypass_list_management(email)
  |> put_google_analytics(email)
+ |> put_click_tracking(email)
  |> put_ip_pool_name(email)
  |> put_unique_args(email)
  end
@@ -355,6 +356,18 @@ defmodule Bamboo.SendGridAdapter do
 
  defp put_google_analytics(body, _), do: body
 
+ defp put_click_tracking(body, %Email{private: %{click_tracking_enabled: enabled}}) do
+ tracking_settings =
+ body
+ |> Map.get(:tracking_settings, %{})
+ |> Map.put(:click_tracking, %{enabled: enabled, enable_text: enabled})
+
+ body
+ |> Map.put(:tracking_settings, tracking_settings)
+ end
+
+ defp put_click_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

@@ -23,6 +23,7 @@ defmodule Bamboo.SendGridHelper do
  @send_at_field :sendgrid_send_at
  @ip_pool_name_field :ip_pool_name
  @unique_args :unique_args
+ @click_tracking_enabled :click_tracking_enabled
 
  @doc """
  Specify the template for SendGrid to use for the context of the substitution
@@ -200,6 +201,27 @@ defmodule Bamboo.SendGridHelper do
  raise "expected with_google_analytics enabled parameter to be a boolean"
  end
 
+ @doc """
+ Instruct SendGrid to enable or disable Click Tracking for a particular email.
+
+ Read more about SendGrid click tracking [here](https://docs.sendgrid.com/ui/account-and-settings/tracking#click-tracking)
+
+ ## Example
+
+ email
+ |> with_click_tracking(true)
+
+ email
+ |> with_click_tracking(false)
+ """
+ def with_click_tracking(email, enabled)
+ when is_boolean(enabled),
+ do: Email.put_private(email, @click_tracking_enabled, enabled)
+
+ def with_click_tracking(_email, _enabled) do
+ raise "expected with_click_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

@@ -335,6 +335,38 @@ defmodule Bamboo.SendGridAdapterTest do
  assert params["tracking_settings"]["ganalytics"]["utm_content"] == "content"
  end
 
+ test "deliver/2 correctly handles when with_click_tracking is enabled" do
+ email =
+ new_email(
+ from: {"From", "[email protected]"},
+ subject: "My Subject"
+ )
+
+ email
+ |> Bamboo.SendGridHelper.with_click_tracking(true)
+ |> SendGridAdapter.deliver(@config)
+
+ assert_receive {:fake_sendgrid, %{params: params}}
+ assert params["tracking_settings"]["click_tracking"]["enabled"] == true
+ assert params["tracking_settings"]["click_tracking"]["enable_text"] == true
+ end
+
+ test "deliver/2 correctly handles when with_click_tracking is disabled" do
+ email =
+ new_email(
+ from: {"From", "[email protected]"},
+ subject: "My Subject"
+ )
+
+ email
+ |> Bamboo.SendGridHelper.with_click_tracking(false)
+ |> SendGridAdapter.deliver(@config)
+
+ assert_receive {:fake_sendgrid, %{params: params}}
+ assert params["tracking_settings"]["click_tracking"]["enabled"] == false
+ assert params["tracking_settings"]["click_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

@@ -183,6 +183,24 @@ defmodule Bamboo.SendGridHelperTest do
  end
  end
 
+ test "with_click_tracking/2 with utm_params", %{email: email} do
+ email = with_click_tracking(email, true)
+
+ assert email.private[:click_tracking_enabled] == true
+ end
+
+ test "with_click_tracking/2 with enabled set false", %{email: email} do
+ email = with_click_tracking(email, false)
+
+ assert email.private[:click_tracking_enabled] == false
+ end
+
+ test "with_click_tracking/2 raises on non-boolean enabled parameter", %{email: email} do
+ assert_raise RuntimeError, fn ->
+ with_click_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")