feat: add ability to define interceptors

README.md

@@ -260,6 +260,38 @@ 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
+# some/path/within/your/app/mailer.ex
+defmodule MyApp.Mailer do
+  use Bamboo.Mailer, otp_app: :my_app, interceptors: [MyApp.BlackListInterceptor]
+end
+```
+
+An interceptor must implement the `Bamboo.Interceptor` behaviour.
+
+```elixir
+# some/path/within/your/app/black_list_interceptor.ex
+defmodule MyApp.BlackListInterceptor do
+  use Bamboo.Interceptor
+
+  @black_list ["bar@foo.com"]
+
+  def call(email) do
+    if email.to in @black_list do
+      :intercepted
+    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/interceptor.ex

@@ -0,0 +1,10 @@
+defmodule Bamboo.Interceptor do
+  @callback call(email :: Bamboo.Email.t()) :: Bamboo.Email.t() | :intercepted
+
+  defmacro __using__(_) do
+    quote do
+      @behaviour Bamboo.Interceptor
+      def call(:intercepted), do: :intercepted
+    end
+  end
+end

lib/bamboo/mailer.ex

@@ -67,29 +67,36 @@ defmodule Bamboo.Mailer do
               {:ok, Bamboo.Email.t()}
               | {:ok, Bamboo.Email.t(), any}
               | {:error, Exception.t() | String.t()}
+
+      interceptors = Keyword.get(opts, :interceptors, [])
+
       def deliver_now(email, opts \\ []) do
         {config, opts} = Keyword.split(opts, [:config])
         config = build_config(config)
+        email = Bamboo.Mailer.intercept(email, unquote(interceptors))
         Bamboo.Mailer.deliver_now(config.adapter, email, config, opts)
       end
 
       @spec deliver_now!(Bamboo.Email.t(), Enum.t()) :: Bamboo.Email.t() | {Bamboo.Email.t(), any}
       def deliver_now!(email, opts \\ []) do
         {config, opts} = Keyword.split(opts, [:config])
         config = build_config(config)
+        email = Bamboo.Mailer.intercept(email, unquote(interceptors))
         Bamboo.Mailer.deliver_now!(config.adapter, email, config, opts)
       end
 
       @spec deliver_later(Bamboo.Email.t()) ::
               {:ok, Bamboo.Email.t()} | {:error, Exception.t() | String.t()}
       def deliver_later(email, opts \\ []) do
         config = build_config(opts)
+        email = Bamboo.Mailer.intercept(email, unquote(interceptors))
         Bamboo.Mailer.deliver_later(config.adapter, email, config)
       end
 
       @spec deliver_later!(Bamboo.Email.t()) :: Bamboo.Email.t()
       def deliver_later!(email, opts \\ []) do
         config = build_config(opts)
+        email = Bamboo.Mailer.intercept(email, unquote(interceptors))
         Bamboo.Mailer.deliver_later!(config.adapter, email, config)
       end
 
@@ -194,6 +201,8 @@ defmodule Bamboo.Mailer do
   end
 
   @doc false
+  def deliver_now(_, :intercepted, _, _), do: nil
+
   def deliver_now(adapter, email, config, opts) do
     with {:ok, email} <- validate_and_normalize(email, adapter) do
       if empty_recipients?(email) do
@@ -211,6 +220,12 @@ defmodule Bamboo.Mailer do
     end
   end
 
+  def intercept(email, interceptors) do
+    Enum.reduce(interceptors, email, fn interceptor, email ->
+      apply(interceptor, :call, [email])
+    end)
+  end
+
   defp format_response(email, response, opts) do
     put_response = Keyword.get(opts, :response, false)
 

mix.exs

@@ -67,7 +67,8 @@ defmodule Bamboo.Mixfile do
       {:floki, "~> 0.29", only: :test},
       {:ex_doc, "~> 0.23", only: :dev},
       {:hackney, ">= 1.15.2"},
-      {:jason, "~> 1.0", optional: true}
+      {:jason, "~> 1.0", optional: true},
+      {:mix_test_watch, "~> 1.0", only: :dev, runtime: false}
     ]
   end
 end

mix.lock

@@ -7,6 +7,7 @@
   "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"},
   "ex_machina": {:hex, :ex_machina, "2.4.0", "09a34c5d371bfb5f78399029194a8ff67aff340ebe8ba19040181af35315eabb", [:mix], [{:ecto, "~> 2.2 or ~> 3.0", [hex: :ecto, repo: "hexpm", optional: true]}, {:ecto_sql, "~> 3.0", [hex: :ecto_sql, repo: "hexpm", optional: true]}], "hexpm", "a20bc9ddc721b33ea913b93666c5d0bdca5cbad7a67540784ae277228832d72c"},
   "excoveralls": {:hex, :excoveralls, "0.13.2", "5ca05099750c086f144fcf75842c363fc15d7d9c6faa7ad323d010294ced685e", [:mix], [{:hackney, "~> 1.16", [hex: :hackney, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "1e7ed75c158808a5a8f019d3ad63a5efe482994f2f8336c0a8c77d2f0ab152ce"},
+  "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "floki": {:hex, :floki, "0.29.0", "b1710d8c93a2f860dc2d7adc390dd808dc2fb8f78ee562304457b75f4c640881", [:mix], [{:html_entities, "~> 0.5.0", [hex: :html_entities, repo: "hexpm", optional: false]}], "hexpm", "008585ce64b9f74c07d32958ec9866f4b8a124bf4da1e2941b28e41384edaaad"},
   "hackney": {:hex, :hackney, "1.16.0", "5096ac8e823e3a441477b2d187e30dd3fff1a82991a806b2003845ce72ce2d84", [:rebar3], [{:certifi, "2.5.2", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "6.0.1", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "1.0.1", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~>1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.3.0", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "1.1.6", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}], "hexpm", "3bf0bebbd5d3092a3543b783bf065165fa5d3ad4b899b836810e513064134e18"},
   "html_entities": {:hex, :html_entities, "0.5.1", "1c9715058b42c35a2ab65edc5b36d0ea66dd083767bef6e3edb57870ef556549", [:mix], [], "hexpm", "30efab070904eb897ff05cd52fa61c1025d7f8ef3a9ca250bc4e6513d16c32de"},
@@ -17,6 +18,7 @@
   "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], [], "hexpm", "69b09adddc4f74a40716ae54d140f93beb0fb8978d8636eaded0c31b6f099f16"},
   "mime": {:hex, :mime, "1.4.0", "5066f14944b470286146047d2f73518cf5cca82f8e4815cf35d196b58cf07c47", [:mix], [], "hexpm", "75fa42c4228ea9a23f70f123c74ba7cece6a03b1fd474fe13f6a7a85c6ea4ff6"},
   "mimerl": {:hex, :mimerl, "1.2.0", "67e2d3f571088d5cfd3e550c383094b47159f3eee8ffa08e64106cdf5e981be3", [:rebar3], [], "hexpm", "f278585650aa581986264638ebf698f8bb19df297f66ad91b18910dfc6e19323"},
+  "mix_test_watch": {:hex, :mix_test_watch, "1.0.2", "34900184cbbbc6b6ed616ed3a8ea9b791f9fd2088419352a6d3200525637f785", [:mix], [{:file_system, "~> 0.2.1 or ~> 0.3", [hex: :file_system, repo: "hexpm", optional: false]}], "hexpm", "47ac558d8b06f684773972c6d04fcc15590abdb97aeb7666da19fcbfdc441a07"},
   "mochiweb": {:hex, :mochiweb, "2.15.0", "e1daac474df07651e5d17cc1e642c4069c7850dc4508d3db7263a0651330aacc", [:rebar3], [], "hexpm", "b960d1cbcf40a30963eeee90ab7aeae074cbfa9a238561fb4434add1afc3075c"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
   "parse_trans": {:hex, :parse_trans, "3.3.0", "09765507a3c7590a784615cfd421d101aec25098d50b89d7aa1d66646bc571c1", [:rebar3], [], "hexpm", "17ef63abde837ad30680ea7f857dd9e7ced9476cdd7b0394432af4bfc241b960"},

test/lib/bamboo/mailer_test.exs

@@ -19,6 +19,12 @@ defmodule Bamboo.MailerTest do
 
   defmodule(Mailer, do: use(Bamboo.Mailer, otp_app: :bamboo))
 
+  defmodule MailerWithInterceptors do
+    use Bamboo.Mailer,
+      otp_app: :bamboo,
+      interceptors: [Bamboo.BlackListInterceptor, Bamboo.EnvInterceptor]
+  end
+
   defmodule DefaultAdapter do
     def deliver(email, config) do
       send(:mailer_test, {:deliver, email, config})
@@ -447,6 +453,26 @@ defmodule Bamboo.MailerTest do
     end
   end
 
+  describe "interceptors" do
+    setup do
+      Application.put_env(:bamboo, __MODULE__.MailerWithInterceptors, @mailer_config)
+    end
+
+    test "must apply interceptor and send email if not intercepted" do
+      email = new_email(to: "foo@bar.com")
+      MailerWithInterceptors.deliver_now(email)
+
+      assert_receive {:deliver, %Bamboo.Email{to: [{nil, "foo@bar.com"}], subject: "test - "},
+                      _config}
+    end
+
+    test "must apply interceptor and block email if intercepted" do
+      email = new_email(to: "bar@foo.com")
+      MailerWithInterceptors.deliver_now(email)
+      refute_receive {:deliver, %Bamboo.Email{to: [{nil, "bar@foo.com"}]}, _config}
+    end
+  end
+
   defp new_email(attrs \\ []) do
     attrs = Keyword.merge([from: "foo@bar.com", to: "foo@bar.com"], attrs)
     Email.new_email(attrs)

test/support/black_list_interceptor.ex

@@ -0,0 +1,13 @@
+defmodule Bamboo.BlackListInterceptor do
+  use Bamboo.Interceptor
+
+  @black_list ["bar@foo.com"]
+
+  def call(email) do
+    if email.to in @black_list do
+      :intercepted
+    else
+      email
+    end
+  end
+end

test/support/env_interceptor.ex

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