Added support for Mailgun tags and templates

CHANGELOG.md

@@ -1,3 +1,10 @@
+## Unreleased - DATE TBD
+
+### New Additions
+
+* Added support Mailgun templates
+* Added support for Mailgun tags
+
 ## [1.2.0] - 2019-01-30
 
 ### New Additions

lib/bamboo/adapters/mailgun_adapter.ex

@@ -5,6 +5,8 @@ defmodule Bamboo.MailgunAdapter do
   Use this adapter to send emails through Mailgun's API. Requires that an API
   key and a domain are set in the config.
 
+  See `Bamboo.MailgunHelper` for extra functions that can be used by Bamboo.MailgunAdapter (tagging, merge vars, etc.)
+
   ## Example config
 
       # In config/config.exs, or config.prod.exs, etc.
@@ -106,6 +108,8 @@ defmodule Bamboo.MailgunAdapter do
     |> put_reply_to(email)
     |> put_attachments(email)
     |> put_headers(email)
+    |> put_tag(email)
+    |> put_template(email)
     |> put_custom_vars(email)
     |> filter_non_empty_mailgun_fields
     |> encode_body
@@ -152,6 +156,14 @@ defmodule Bamboo.MailgunAdapter do
     end)
   end
 
+  defp put_tag(body, %Email{private: %{:"o:tag" => tag}}), do: Map.put(body, :"o:tag", tag)
+  defp put_tag(body, %Email{}), do: body
+
+  defp put_template(body, %Email{private: %{template: template}}),
+    do: Map.put(body, :template, template)
+
+  defp put_template(body, %Email{}), do: body
+
   defp put_custom_vars(body, %Email{private: private}) do
     custom_vars = Map.get(private, :mailgun_custom_vars, %{})
 
@@ -176,14 +188,15 @@ defmodule Bamboo.MailgunAdapter do
      {"form-data", [{"name", ~s/"attachment"/}, {"filename", ~s/"#{attachment.filename}"/}]}, []}
   end
 
-  @mailgun_message_fields ~w(from to cc bcc subject text html)a
+  @mailgun_message_fields ~w(from to cc bcc subject text html template)a
   @internal_fields ~w(attachments)a
 
   def filter_non_empty_mailgun_fields(body) do
     Enum.filter(body, fn {key, value} ->
       # Key is a well known mailgun field (including header and custom var field) and its value is not empty
       (key in @mailgun_message_fields || key in @internal_fields ||
-         String.starts_with?(Atom.to_string(key), ["h:", "v:"])) && !(value in [nil, "", []])
+         String.starts_with?(Atom.to_string(key), ["h:", "v:", "o:"])) &&
+        !(value in [nil, "", []])
     end)
     |> Enum.into(%{})
   end

lib/bamboo/adapters/mailgun_helper.ex

@@ -0,0 +1,70 @@
+defmodule Bamboo.MailgunHelper do
+  @moduledoc """
+  Functions for using features specific to Mailgun
+  (e.g. tagging, templates).
+  """
+
+  alias Bamboo.Email
+
+  @doc """
+  Add a tag to outgoing email to help categorize traffic based on some
+  criteria, perhaps separate signup emails from password recovery emails
+  or from user comments.
+
+  More details can be found in the
+  [Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#tagging)
+
+  ## Example
+
+      email
+      |> MailgunHelper.tag("welcome-email")
+  """
+  def tag(email, tag) do
+    Email.put_private(email, :"o:tag", tag)
+  end
+
+  @doc """
+  Send an email using a template stored in Mailgun, rather than supplying
+  a `Bamboo.Email.text_body/2` or a `Bamboo.Email.html_body/2`.
+
+  More details about templates can be found in the
+  [Templates section of the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#templates).
+  """
+  def template(email, template_name) do
+    Email.put_private(email, :template, template_name)
+  end
+
+  @doc """
+  When sending an email with `Bamboo.MailgunHelper.template/2` you can
+  replace a handlebars variables using this function.
+
+  More details about templates can be found in the
+  [Templates section of the Mailgun documentation](https://documentation.mailgun.com/en/latest/user_manual.html#templates).
+
+  ## Example
+
+      email
+      |> MailgunHelper.template("password-reset-email")
+      |> MailgunHelper.substitute_variables("password_reset_link", "https://example.com/123")
+
+  """
+  def substitute_variables(email, key, value) do
+    substitute_variables(email, %{key => value})
+  end
+
+  @doc """
+  This behaves like `Bamboo.MailgunHelper.substitute_variables/3`, but
+  accepts a `Map` rather than a key, value pair.
+
+  ## Example
+
+      email
+      |> MailgunHelper.template("password-reset-email")
+      |> MailgunHelper.substitute_variables(%{ "greeting" => "Hello!", "password_reset_link" => "https://example.com/123" })
+
+  """
+  def substitute_variables(email, variables = %{}) do
+    custom_vars = Map.get(email.private, :mailgun_custom_vars, %{})
+    Email.put_private(email, :mailgun_custom_vars, Map.merge(custom_vars, variables))
+  end
+end

test/lib/bamboo/adapters/mailgun_helper_test.exs

@@ -0,0 +1,36 @@
+defmodule Bamboo.MailgunHelperTest do
+  use ExUnit.Case
+  import Bamboo.Email
+  alias Bamboo.MailgunHelper
+
+  test "tag/2 puts a tag in private" do
+    email = new_email() |> MailgunHelper.tag("new-tag")
+
+    assert Map.get(Map.get(email, :private, %{}), :"o:tag", nil) == "new-tag"
+  end
+
+  test "adds template information to mailgun emails" do
+    email =
+      new_email()
+      |> MailgunHelper.template("welcome")
+
+    assert email.private == %{template: "welcome"}
+  end
+
+  test "adds template substitution variables to mailgun emails" do
+    email =
+      new_email()
+      |> MailgunHelper.substitute_variables("var1", "val1")
+      |> MailgunHelper.substitute_variables(%{"var2" => "val2", "var3" => "val3"})
+      |> MailgunHelper.substitute_variables("var4", "val4")
+
+    assert email.private == %{
+             mailgun_custom_vars: %{
+               "var1" => "val1",
+               "var2" => "val2",
+               "var3" => "val3",
+               "var4" => "val4"
+             }
+           }
+  end
+end