Adds ability to define interceptors (#591)

This commit adds the ability to define custom email interceptors. 

Interceptors are modules that abide by an interceptor behaviour 
and are configured alongside Bamboo's config. 

Why interceptors?
-------------------

Interceptors can be used to either modify emails or prevent them
from going out. 

For example, we may want to:

- rewrite subject for a given environment (e.g. prefix [environment] to subject)
- rewrite email `to` address so that it only sends to allowed addresses 
   in dev/staging
- block outbound emails for a given environment (staging, dev,...)
- block email in case the recipient is blocked (bounces, complaints, ...)

README.md

@@ -260,6 +260,37 @@ struct directly to Bamboo anywhere it expects an address. See the
 [`Bamboo.Email`] and [`Bamboo.Formatter`] docs for more information and
 examples.
 
+## Interceptors
+
+It's possible to configure per Mailer interceptors. Interceptors allow
+to modify / intercept (block) email on the fly.
+
+```elixir
+# config/config.exs
+config :my_app, MyApp.Mailer,
+  adapter: Bamboo.MandrillAdapter,
+  interceptors: [MyApp.DenyListInterceptor]
+end
+```
+
+An interceptor must implement the `Bamboo.Interceptor` behaviour. To prevent email being sent, you can block it with `Bamboo.Email.block/1`.
+
+```elixir
+# some/path/within/your/app/deny_list_interceptor.ex
+defmodule MyApp.DenyListInterceptor do
+  @behaviour Bamboo.Interceptor
+  @deny_list ["[email protected]"]
+
+  def call(email) do
+    if email.to in @deny_list do
+      Bamboo.Email.block(email)
+    else
+      email
+    end
+  end
+end
+```
+
 ## Using Phoenix Views and Layouts
 
 Phoenix is not required to use Bamboo. But if you want to use Phoenix's views

lib/bamboo/email.ex

@@ -83,7 +83,8 @@ defmodule Bamboo.Email do
           text_body: nil | String.t(),
           headers: %{String.t() => String.t()},
           assigns: %{atom => any},
-          private: %{atom => any}
+          private: %{atom => any},
+          blocked: boolean()
         }
 
   defstruct from: nil,
@@ -96,7 +97,8 @@ defmodule Bamboo.Email do
             headers: %{},
             attachments: [],
             assigns: %{},
-            private: %{}
+            private: %{},
+            blocked: false
 
   alias Bamboo.{Email, Attachment}
 
@@ -263,4 +265,8 @@ defmodule Bamboo.Email do
   def put_attachment(%__MODULE__{attachments: attachments} = email, path, opts \\ []) do
     %{email | attachments: [Bamboo.Attachment.new(path, opts) | attachments]}
   end
+
+  def block(email) do
+    %{email | blocked: true}
+  end
 end

lib/bamboo/interceptor.ex

@@ -0,0 +1,24 @@
+defmodule Bamboo.Interceptor do
+  @moduledoc ~S"""
+  Behaviour for creating an Interceptor.
+
+  An interceptor allow to modify / block an email before it is sent. To block an email, it must be marked as intercepted with `Bamboo.Email.intercept/1`.
+
+  ## Example
+
+      defmodule Bamboo.DenyListInterceptor do
+        @behaviour Bamboo.Interceptor
+        @deny_list ["[email protected]"]
+
+        def call(email) do
+          if email.to in @deny_list do
+            Bamboo.Email.intercept(email)
+          else
+            email
+          end
+        end
+      end
+  """
+
+  @callback call(email :: Bamboo.Email.t()) :: Bamboo.Email.t()
+end

lib/bamboo/mailer.ex

@@ -67,6 +67,7 @@ defmodule Bamboo.Mailer do
               {:ok, Bamboo.Email.t()}
               | {:ok, Bamboo.Email.t(), any}
               | {:error, Exception.t() | String.t()}
+
       def deliver_now(email, opts \\ []) do
         {config, opts} = Keyword.split(opts, [:config])
         config = build_config(config)
@@ -195,7 +196,8 @@ defmodule Bamboo.Mailer do
 
   @doc false
   def deliver_now(adapter, email, config, opts) do
-    with {:ok, email} <- validate_and_normalize(email, adapter) do
+    with {:ok, email} <- validate_and_normalize(email, adapter),
+         %Bamboo.Email{blocked: false} = email <- apply_interceptors(email, config) do
       if empty_recipients?(email) do
         debug_unsent(email)
 
@@ -208,6 +210,9 @@ defmodule Bamboo.Mailer do
           {:error, _} = error -> error
         end
       end
+    else
+      %Bamboo.Email{blocked: true} = email -> {:ok, email}
+      response -> response
     end
   end
 
@@ -232,7 +237,8 @@ defmodule Bamboo.Mailer do
 
   @doc false
   def deliver_later(adapter, email, config) do
-    with {:ok, email} <- validate_and_normalize(email, adapter) do
+    with {:ok, email} <- validate_and_normalize(email, adapter),
+         %Bamboo.Email{blocked: false} = email <- apply_interceptors(email, config) do
       if empty_recipients?(email) do
         debug_unsent(email)
       else
@@ -241,6 +247,9 @@ defmodule Bamboo.Mailer do
       end
 
       {:ok, email}
+    else
+      %Bamboo.Email{blocked: true} = email -> {:ok, email}
+      response -> response
     end
   end
 
@@ -333,6 +342,14 @@ defmodule Bamboo.Mailer do
 
   defp is_nil_recipient?(_), do: false
 
+  defp apply_interceptors(email, config) do
+    interceptors = config[:interceptors] || []
+
+    Enum.reduce(interceptors, email, fn interceptor, email ->
+      apply(interceptor, :call, [email])
+    end)
+  end
+
   @doc """
   Wraps to, cc and bcc addresses in a list and normalizes email addresses.
 

test/lib/bamboo/email_test.exs

@@ -116,4 +116,10 @@ defmodule Bamboo.EmailTest do
 
     assert [%Bamboo.Attachment{filename: "attachment.docx"}] = email.attachments
   end
+
+  test "block/1 mark email as blocked" do
+    email = new_email()
+    refute email.blocked
+    assert %Bamboo.Email{blocked: true} = block(email)
+  end
 end

test/lib/bamboo/mailer_test.exs

@@ -2,14 +2,18 @@ defmodule Bamboo.MailerTest do
   use ExUnit.Case
   alias Bamboo.Email
 
-  @mailer_config adapter: __MODULE__.DefaultAdapter, foo: :bar
+  @mailer_config adapter: __MODULE__.DefaultAdapter, foo: :bar, interceptors: nil
 
   setup context do
     config =
-      Keyword.merge(@mailer_config, [adapter: context[:adapter]], fn
-        _key, default, nil -> default
-        _key, _default, override -> override
-      end)
+      Keyword.merge(
+        @mailer_config,
+        [adapter: context[:adapter], interceptors: context[:interceptors]],
+        fn
+          _key, default, nil -> default
+          _key, _default, override -> override
+        end
+      )
 
     Application.put_env(:bamboo, __MODULE__.Mailer, config)
     Process.register(self(), :mailer_test)
@@ -447,6 +451,76 @@ defmodule Bamboo.MailerTest do
     end
   end
 
+  describe "interceptors" do
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_now/1 must apply interceptors and send email if not intercepted" do
+      email = new_email(to: "[email protected]")
+      assert {:ok, %Bamboo.Email{blocked: false}} = Mailer.deliver_now(email)
+
+      assert_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}], subject: "test - "},
+                      _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_now/1 must apply interceptors and block email if intercepted" do
+      email = new_email(to: "[email protected]")
+      assert {:ok, %Bamboo.Email{blocked: true}} = Mailer.deliver_now(email)
+      refute_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}]}, _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_now!/1 must apply interceptors and send email if not intercepted" do
+      email = new_email(to: "[email protected]")
+      assert %Bamboo.Email{blocked: false} = Mailer.deliver_now!(email)
+
+      assert_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}], subject: "test - "},
+                      _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_now!/1 must apply interceptors and block email if intercepted" do
+      email = new_email(to: "[email protected]")
+
+      assert %Bamboo.Email{blocked: true} = Mailer.deliver_now!(email)
+
+      refute_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}]}, _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_later/1 must apply interceptors and send email if not intercepted" do
+      email = new_email(to: "[email protected]")
+      assert {:ok, %Bamboo.Email{blocked: false}} = Mailer.deliver_later(email)
+
+      assert_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}], subject: "test - "},
+                      _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_later/1 must apply interceptors and block email if intercepted" do
+      email = new_email(to: "[email protected]")
+
+      assert {:ok, %Bamboo.Email{blocked: true}} = Mailer.deliver_later(email)
+
+      refute_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}]}, _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_later!/1 must apply interceptors and send email if not intercepted" do
+      email = new_email(to: "[email protected]")
+      assert %Bamboo.Email{blocked: false} = Mailer.deliver_later!(email)
+
+      assert_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}], subject: "test - "},
+                      _config}
+    end
+
+    @tag interceptors: [Bamboo.DenyListInterceptor, Bamboo.EnvInterceptor]
+    test "deliver_later!/1 must apply interceptors and block email if intercepted" do
+      email = new_email(to: "[email protected]")
+      assert %Bamboo.Email{blocked: true} = Mailer.deliver_later!(email)
+      refute_receive {:deliver, %Bamboo.Email{to: [{nil, "[email protected]"}]}, _config}
+    end
+  end
+
   defp new_email(attrs \\ []) do
     attrs = Keyword.merge([from: "[email protected]", to: "[email protected]"], attrs)
     Email.new_email(attrs)

test/support/deny_list_interceptor.ex

@@ -0,0 +1,13 @@
+defmodule Bamboo.DenyListInterceptor do
+  @behaviour Bamboo.Interceptor
+
+  @deny_list ["[email protected]"]
+
+  def call(email) do
+    if Enum.any?(email.to, &(elem(&1, 1) in @deny_list)) do
+      Bamboo.Email.block(email)
+    else
+      email
+    end
+  end
+end

test/support/env_interceptor.ex

@@ -0,0 +1,9 @@
+defmodule Bamboo.EnvInterceptor do
+  @behaviour Bamboo.Interceptor
+
+  @env Mix.env()
+
+  def call(email) do
+    %{email | subject: "#{@env} - #{email.subject}"}
+  end
+end