feat: Add support for all Mailgun o: options (#718)

* feat: add new method to mailgun helper and adapter that allow to add different  properties to body

* refactor: format files using mix format

Author: yoelfme

lib/bamboo/adapters/mailgun_adapter.ex

@@ -56,6 +56,22 @@ defmodule Bamboo.MailgunAdapter do
   @internal_fields ~w(attachments)a
   @mailgun_message_fields ~w(from to cc bcc subject text html template recipient-variables)a
   @service_name "Mailgun"
+  @allowed_mailgun_o_options [
+    :"o:tag",
+    :"o:dkim",
+    :"o:deliverytime",
+    :"o:testmode",
+    :"o:tracking",
+    :"o:tracking-clicks",
+    :"o:tracking-opens",
+    :"o:require-tls",
+    :"o:skip-verification",
+    :"o:sending-ip",
+    :"o:sending-ip-pool",
+    :"o:tracking-pixel-location-top",
+    :"o:secondary-dkim",
+    :"o:secondary-dkim-public"
+  ]
 
   @doc false
   def handle_config(config) do
@@ -151,6 +167,7 @@ defmodule Bamboo.MailgunAdapter do
     |> put_template_version(email)
     |> put_template_text(email)
     |> put_custom_vars(email)
+    |> put_options(email)
     |> put_recipient_variables(email)
     |> filter_non_empty_mailgun_fields
     |> encode_body
@@ -196,6 +213,8 @@ defmodule Bamboo.MailgunAdapter do
     end)
   end
 
+  # Deprecated: use put_options instead. These are kept for backward compatibility.
+  # Will be removed in a future release.
   defp put_tag(body, %Email{private: %{:"o:tag" => tag}}), do: Map.put(body, :"o:tag", tag)
   defp put_tag(body, %Email{}), do: body
 
@@ -252,6 +271,15 @@ defmodule Bamboo.MailgunAdapter do
     {"", attachment.data, {"form-data", [{"name", ~s/"attachment"/}, {"filename", ~s/"#{attachment.filename}"/}]}, []}
   end
 
+  defp put_options(body, %Email{private: private}) do
+    Enum.reduce(@allowed_mailgun_o_options, body, fn key, acc ->
+      case Map.fetch(private, key) do
+        {:ok, value} -> Map.put(acc, key, value)
+        :error -> acc
+      end
+    end)
+  end
+
   def filter_non_empty_mailgun_fields(body) do
     body
     |> Enum.filter(fn {key, value} ->

lib/bamboo/adapters/mailgun_helper.ex

@@ -8,6 +8,23 @@ defmodule Bamboo.MailgunHelper do
 
   @mailgun_header_for_custom_vars "X-Mailgun-Variables"
 
+  @allowed_mailgun_o_options [
+    :"o:tag",
+    :"o:dkim",
+    :"o:deliverytime",
+    :"o:testmode",
+    :"o:tracking",
+    :"o:tracking-clicks",
+    :"o:tracking-opens",
+    :"o:require-tls",
+    :"o:skip-verification",
+    :"o:sending-ip",
+    :"o:sending-ip-pool",
+    :"o:tracking-pixel-location-top",
+    :"o:secondary-dkim",
+    :"o:secondary-dkim-public"
+  ]
+
   @doc """
   Add a tag to outgoing email to help categorize traffic based on some
   criteria, perhaps separate signup emails from password recovery emails
@@ -147,4 +164,27 @@ defmodule Bamboo.MailgunHelper do
     encoded_value = Bamboo.json_library().encode!(value)
     Email.put_private(email, :mailgun_recipient_variables, encoded_value)
   end
+
+  @doc """
+  Set a Mailgun option (`o:` parameter) on the email in a safe, validated way.
+
+  Only the options allowed by the Mailgun API are supported. See:
+  https://mailgun-docs.redoc.ly/docs/mailgun/api-reference/openapi-final/tag/Messages/#tag/Messages/operation/POST-v3--domain-name--messages
+
+  ## Example
+
+      email
+      |> MailgunHelper.option(:"o:tracking", "yes")
+      |> MailgunHelper.option(:"o:tracking-clicks", "htmlonly")
+
+  If you try to set an unsupported option, an ArgumentError will be raised.
+  """
+  def option(email, key, value) when key in @allowed_mailgun_o_options do
+    Email.put_private(email, key, value)
+  end
+
+  def option(_email, key, _value) do
+    raise ArgumentError,
+          "#{inspect(key)} is not a supported Mailgun option. See the Mailgun API docs for allowed options."
+  end
 end

test/lib/bamboo/adapters/mailgun_adapter_test.exs

@@ -287,6 +287,76 @@ defmodule Bamboo.MailgunAdapterTest do
     assert params["t:text"] == "yes"
   end
 
+  test "deliver/2 includes whitelisted o: options from private" do
+    email =
+      [from: "from@foo.com", subject: "My Subject", text_body: "TEXT BODY", html_body: "HTML BODY"]
+      |> new_email()
+      |> Email.put_private(:"o:tracking", "yes")
+      |> Email.put_private(:"o:tracking-clicks", "htmlonly")
+      |> Email.put_private(:"o:dkim", "yes")
+      |> Email.put_private(:"o:testmode", "true")
+
+    MailgunAdapter.deliver(email, @config)
+
+    assert_receive {:fake_mailgun, %{params: params}}
+
+    assert params["o:tracking"] == "yes"
+    assert params["o:tracking-clicks"] == "htmlonly"
+    assert params["o:dkim"] == "yes"
+    assert params["o:testmode"] == "true"
+  end
+
+  test "deliver/2 ignores unsupported o: options from private" do
+    email =
+      [from: "from@foo.com", subject: "My Subject", text_body: "TEXT BODY", html_body: "HTML BODY"]
+      |> new_email()
+      |> Email.put_private(:"o:tracking", "yes")
+      |> Email.put_private(:"o:unsupported-option", "value")
+      |> Email.put_private(:"o:invalid", "should-be-ignored")
+
+    MailgunAdapter.deliver(email, @config)
+
+    assert_receive {:fake_mailgun, %{params: params}}
+
+    # Supported option should be included
+    assert params["o:tracking"] == "yes"
+
+    # Unsupported options should be ignored
+    refute Map.has_key?(params, "o:unsupported-option")
+    refute Map.has_key?(params, "o:invalid")
+  end
+
+  test "deliver/2 works with all allowed o: options" do
+    email =
+      [from: "from@foo.com", subject: "My Subject", text_body: "TEXT BODY", html_body: "HTML BODY"]
+      |> new_email()
+      |> Email.put_private(:"o:tag", ["tag1", "tag2"])
+      |> Email.put_private(:"o:deliverytime", "Wed, 15 Nov 2023 09:30:00 +0000")
+      |> Email.put_private(:"o:tracking-opens", "yes")
+      |> Email.put_private(:"o:require-tls", "true")
+      |> Email.put_private(:"o:skip-verification", "false")
+      |> Email.put_private(:"o:sending-ip", "192.168.1.1")
+      |> Email.put_private(:"o:sending-ip-pool", "pool-123")
+      |> Email.put_private(:"o:tracking-pixel-location-top", "yes")
+      |> Email.put_private(:"o:secondary-dkim", "example.com/s1")
+      |> Email.put_private(:"o:secondary-dkim-public", "public.com/s1")
+
+    MailgunAdapter.deliver(email, @config)
+
+    assert_receive {:fake_mailgun, %{params: params}}
+
+    assert params["o:tag"] == ["tag1", "tag2"]
+    assert params["o:deliverytime"] == "Wed, 15 Nov 2023 09:30:00 +0000"
+    assert params["o:tracking-opens"] == "yes"
+    assert params["o:require-tls"] == "true"
+    assert params["o:skip-verification"] == "false"
+    assert params["o:sending-ip"] == "192.168.1.1"
+    assert params["o:sending-ip-pool"] == "pool-123"
+    assert params["o:tracking-pixel-location-top"] == "yes"
+    assert params["o:secondary-dkim"] == "example.com/s1"
+    assert params["o:secondary-dkim-public"] == "public.com/s1"
+  end
+
   test "returns an error if the response is not a success" do
     email = new_email(from: "INVALID_EMAIL")
 

test/lib/bamboo/adapters/mailgun_helper_test.exs

@@ -71,4 +71,35 @@ defmodule Bamboo.MailgunHelperTest do
              mailgun_recipient_variables: "{\"user1@example.com\":{\"unique_id\":\"ABC123456789\"}}"
            }
   end
+
+  test "option/3 adds allowed o: options to private" do
+    email = MailgunHelper.option(new_email(), :"o:tracking", "yes")
+    assert email |> Map.get(:private, %{}) |> Map.get(:"o:tracking") == "yes"
+
+    email = MailgunHelper.option(email, :"o:tracking-clicks", "htmlonly")
+    assert email |> Map.get(:private, %{}) |> Map.get(:"o:tracking-clicks") == "htmlonly"
+  end
+
+  test "option/3 raises error for unsupported o: options" do
+    assert_raise ArgumentError, ~r/not a supported Mailgun option/, fn ->
+      MailgunHelper.option(new_email(), :"o:unsupported", "value")
+    end
+
+    assert_raise ArgumentError, ~r/not a supported Mailgun option/, fn ->
+      MailgunHelper.option(new_email(), :"o:invalid-option", "value")
+    end
+  end
+
+  test "option/3 works with all allowed o: options" do
+    email = new_email()
+
+    # Test a few more allowed options
+    email = MailgunHelper.option(email, :"o:dkim", "yes")
+    email = MailgunHelper.option(email, :"o:testmode", "yes")
+    email = MailgunHelper.option(email, :"o:require-tls", "true")
+
+    assert email.private[:"o:dkim"] == "yes"
+    assert email.private[:"o:testmode"] == "yes"
+    assert email.private[:"o:require-tls"] == "true"
+  end
 end