Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

Implement e-mail sending suppression (#6681)

Adam44336037ee17
diff --git a/lib/plausible/email_suppression.ex b/lib/plausible/email_suppression.ex
new file mode 100644
index 0000000000..338a336a74
--- /dev/null
+++ b/lib/plausible/email_suppression.ex
@@ -0,0 +1,66 @@
+defmodule Plausible.EmailSuppression do
+ @moduledoc """
+ A record of email addresses we should not send transactional mail to,
+ because Postmark has reported it as bouncing or complaining.
+ """
+
+ use Ecto.Schema
+
+ import Ecto.Changeset
+
+ @type t() :: %__MODULE__{}
+
+ @reasons [:hard_bounce, :bad_email_address, :blocked, :spam_complaint, :manual]
+ @sources [:webhook, :backfill, :manual]
+
+ schema "email_suppressions" do
+ field :email, :string
+ field :reason, Ecto.Enum, values: @reasons
+ field :source, Ecto.Enum, values: @sources
+ # so we can look the bounce back up via e.g. /bounces API
+ field :postmark_bounce_id, :integer
+
+ # Mirrors Postmark's own `Inactive` flag: refusal to send to
+ # this address itself once true, independently of our internal records
+ field :postmark_inactive, :boolean, default: false
+
+ # Mirrors Postmark's own `CanActivate` flag. Some bounce types
+ # are permanent on Postmark's end
+ field :can_activate, :boolean, default: false
+
+ # Postmark's short human-readable explanation for the bounce (`Details` field),
+ # kept for context when under manual CS inspection
+ field :details, :string
+
+ # Set once CS has manually cleared this suppression after review.
+ # A date value here means the address is not suppressed anymore
+ field :reactivated_at, :naive_datetime
+
+ belongs_to :reactivated_by, Plausible.Auth.User, foreign_key: :reactivated_by_user_id
+
+ timestamps()
+ end
+
+ @required [:email, :reason, :source]
+ @optional [:postmark_bounce_id, :postmark_inactive, :can_activate, :details]
+
+ @spec changeset(t(), map()) :: Ecto.Changeset.t()
+ def changeset(suppression, attrs) do
+ suppression
+ |> cast(attrs, @required ++ @optional)
+ |> validate_required(@required)
+ |> unique_constraint(:email)
+ # A fresh bounce/complaint is evidence the address is still bad, so any
+ # earlier reactivation no longer holds
+ |> put_change(:reactivated_at, nil)
+ |> put_change(:reactivated_by_user_id, nil)
+ end
+
+ @spec reactivate_changeset(t(), pos_integer()) :: Ecto.Changeset.t()
+ def reactivate_changeset(suppression, user_id) do
+ change(suppression,
+ reactivated_at: NaiveDateTime.utc_now() |> NaiveDateTime.truncate(:second),
+ reactivated_by_user_id: user_id
+ )
+ end
+end
diff --git a/lib/plausible/email_suppressions.ex b/lib/plausible/email_suppressions.ex
new file mode 100644
index 0000000000..8f6483c94c
--- /dev/null
+++ b/lib/plausible/email_suppressions.ex
@@ -0,0 +1,110 @@
+defmodule Plausible.EmailSuppressions do
+ @moduledoc """
+ Tracks email addresses we should not attempt to send transactional mail to
+ and guards `Plausible.Mailer` against sending to them.
+
+ Entries are created from Postmark bounce/spam-complaint webhooks and from a
+ one-off backfill against the Postmark Bounce API. A suppression is lifted by
+ a manual review (e.g. via the customer support module), which is recorded
+ as a `reactivated_at`/`reactivated_by_user_id` pair on the record.
+ """
+
+ import Ecto.Query
+
+ alias Plausible.EmailSuppression
+ alias Plausible.Repo
+
+ @replace_on_conflict [
+ :reason,
+ :source,
+ :postmark_bounce_id,
+ :postmark_inactive,
+ :can_activate,
+ :details,
+ :reactivated_at,
+ :reactivated_by_user_id,
+ :updated_at
+ ]
+
+ @doc """
+ Returns whether the given e-mail address is currently suppressed, i.e.
+ whether `Plausible.Mailer` should refuse to send to it.
+
+ A suppression that has been manually reactivated is no longer considered
+ suppressed.
+ """
+ @spec suppressed?(String.t()) :: boolean()
+ def suppressed?(email) when is_binary(email) do
+ EmailSuppression
+ |> where([s], s.email == ^email and is_nil(s.reactivated_at))
+ |> Repo.exists?()
+ end
+
+ @doc """
+ Records (or refreshes) a suppression originating from a Postmark bounce.
+
+ If the address is already suppressed, the record is refreshed with the
+ latest bounce details. If the address had been manually
+ reactivated previously, the new bounce takes precedence and re-suppresses it.
+ """
+ @spec create_from_bounce(map()) :: {:ok, EmailSuppression.t()} | {:error, Ecto.Changeset.t()}
+ def create_from_bounce(attrs) do
+ attrs
+ |> Map.take([
+ :email,
+ :reason,
+ :source,
+ :postmark_bounce_id,
+ :postmark_inactive,
+ :can_activate,
+ :details
+ ])
+ |> upsert()
+ end
+
+ @doc """
+ Records (or refreshes) a suppression originating from Postmark spam
+ complaint.
+ """
+ @spec create_from_spam_complaint(map()) ::
+ {:ok, EmailSuppression.t()} | {:error, Ecto.Changeset.t()}
+ def create_from_spam_complaint(attrs) do
+ attrs
+ |> Map.take([
+ :email,
+ :source,
+ :postmark_bounce_id,
+ :postmark_inactive,
+ :can_activate,
+ :details
+ ])
+ |> Map.put(:reason, :spam_complaint)
+ |> upsert()
+ end
+
+ @doc """
+ Lifts a suppression after manual review, recording who did it.
+ """
+ @spec reactivate(String.t(), Plausible.Auth.User.t()) ::
+ {:ok, EmailSuppression.t()} | {:error, :not_found | Ecto.Changeset.t()}
+ def reactivate(email, %Plausible.Auth.User{id: user_id}) do
+ case Repo.get_by(EmailSuppression, email: email) do
+ nil ->
+ {:error, :not_found}
+
+ suppression ->
+ suppression
+ |> EmailSuppression.reactivate_changeset(user_id)
+ |> Repo.update()
+ end
+ end
+
+ defp upsert(attrs) do
+ %EmailSuppression{}
+ |> EmailSuppression.changeset(attrs)
+ |> Repo.insert(
+ on_conflict: {:replace, @replace_on_conflict},
+ conflict_target: :email
+ )
+ end
+end
diff --git a/lib/plausible/mailer.ex b/lib/plausible/mailer.ex
index 6fc23fb97f..46f28faea6 100644
--- a/lib/plausible/mailer.ex
+++ b/lib/plausible/mailer.ex
@@ -1,9 +1,24 @@
defmodule Plausible.Mailer do
use Bamboo.Mailer, otp_app: :plausible
+ use Plausible
require Logger
- @spec send(Bamboo.Email.t()) :: :ok | {:error, :unknown_error}
+ @spec send(Bamboo.Email.t()) :: :ok | {:error, :unknown_error | :suppressed}
def send(email) do
+ case suppressed_recipients(email) do
+ [] ->
+ do_send(email)
+
+ suppressed ->
+ Logger.warning(
+ "Not sending e-mail, recipient(s) are suppressed: #{Enum.join(suppressed, ", ")}"
+ )
+
+ {:error, :suppressed}
+ end
+ end
+
+ defp do_send(email) do
try do
deliver_now!(email)
rescue
@@ -19,4 +34,48 @@ defmodule Plausible.Mailer do
_sent_email -> :ok
end
end
+
+ defp suppressed_recipients(email)
+
+ on_ce do
+ defp suppressed_recipients(_email) do
+ # trick the type checker
+ if always(true), do: [], else: ["unreachable"]
+ end
+ end
+
+ on_ee do
+ defp suppressed_recipients(email) do
+ address = sole_recipient(email)
+
+ cond do
+ # Priority-stream mail (password resets, 2FA, e-mail verification)
+ # has to go through even to an address we'd otherwise suppress -
+ # refusing it could lock someone out of their own account.
+ priority_stream?(email) ->
+ []
+
+ Plausible.EmailSuppressions.suppressed?(address) ->
+ [address]
+
+ true ->
+ []
+ end
+ end
+
+ defp sole_recipient(email) do
+ case Bamboo.Mailer.normalize_addresses(email).to do
+ [{_name, address}] ->
+ address
+
+ to ->
+ # this can be handled in the future, but currently isn't ever used
+ raise "Plausible.Mailer only supports a single `to` recipient, got: #{inspect(to)}"
+ end
+ end
+
+ defp priority_stream?(email) do
+ get_in(email.private, [:message_params, "MessageStream"]) == "priority"
+ end
+ end
end
diff --git a/test/plausible/email_suppressions_test.exs b/test/plausible/email_suppressions_test.exs
new file mode 100644
index 0000000000..c68f1661f0
--- /dev/null
+++ b/test/plausible/email_suppressions_test.exs
@@ -0,0 +1,195 @@
+defmodule Plausible.EmailSuppressionsTest do
+ use Plausible.DataCase
+
+ alias Plausible.EmailSuppressions
+
+ @moduletag :ee_only
+
+ describe "suppressed?/1" do
+ test "false when no record exists" do
+ refute EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "true after a bounce is recorded" do
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook,
+ postmark_bounce_id: 123,
+ postmark_inactive: true,
+ can_activate: true,
+ details: "Unknown user"
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "is case-insensitive" do
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "false again after reactivation" do
+ user = insert(:user)
+
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ assert {:ok, _} = EmailSuppressions.reactivate("[email protected]", user)
+ refute EmailSuppressions.suppressed?("[email protected]")
+ end
+ end
+
+ describe "create_from_bounce/1" do
+ test "requires email, reason and source" do
+ assert {:error, changeset} = EmailSuppressions.create_from_bounce(%{})
+
+ assert {"can't be blank", _} = changeset.errors[:email]
+ assert {"can't be blank", _} = changeset.errors[:reason]
+ assert {"can't be blank", _} = changeset.errors[:source]
+ end
+
+ test "refreshes the existing record instead of failing on duplicate email" do
+ {:ok, first} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook,
+ postmark_bounce_id: 1
+ })
+
+ {:ok, second} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :blocked,
+ source: :webhook,
+ postmark_bounce_id: 2
+ })
+
+ assert first.id == second.id
+ assert second.reason == :blocked
+ assert second.postmark_bounce_id == 2
+ end
+
+ test "a fresh bounce re-suppresses a previously reactivated address" do
+ user = insert(:user)
+
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ {:ok, _} = EmailSuppressions.reactivate("[email protected]", user)
+ refute EmailSuppressions.suppressed?("[email protected]")
+
+ {:ok, suppression} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ assert is_nil(suppression.reactivated_at)
+ assert is_nil(suppression.reactivated_by_user_id)
+ end
+
+ test "a bounce webhook clears a reactivation left by an earlier, different webhook" do
+ user = insert(:user)
+
+ {:ok, _} =
+ EmailSuppressions.create_from_spam_complaint(%{
+ email: "[email protected]",
+ source: :webhook
+ })
+
+ {:ok, _} = EmailSuppressions.reactivate("[email protected]", user)
+ refute EmailSuppressions.suppressed?("[email protected]")
+
+ {:ok, suppression} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ assert suppression.reason == :hard_bounce
+ assert is_nil(suppression.reactivated_at)
+ assert is_nil(suppression.reactivated_by_user_id)
+ end
+ end
+
+ describe "create_from_spam_complaint/1" do
+ test "sets reason to :spam_complaint" do
+ {:ok, suppression} =
+ EmailSuppressions.create_from_spam_complaint(%{
+ email: "[email protected]",
+ source: :webhook
+ })
+
+ assert suppression.reason == :spam_complaint
+ assert EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "a spam complaint webhook clears a reactivation left by an earlier bounce" do
+ user = insert(:user)
+
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ {:ok, _} = EmailSuppressions.reactivate("[email protected]", user)
+ refute EmailSuppressions.suppressed?("[email protected]")
+
+ {:ok, suppression} =
+ EmailSuppressions.create_from_spam_complaint(%{
+ email: "[email protected]",
+ source: :webhook
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ assert suppression.reason == :spam_complaint
+ assert is_nil(suppression.reactivated_at)
+ assert is_nil(suppression.reactivated_by_user_id)
+ end
+ end
+
+ describe "reactivate/2" do
+ test "returns :not_found when there is no suppression for the address" do
+ user = insert(:user)
+ assert {:error, :not_found} = EmailSuppressions.reactivate("[email protected]", user)
+ end
+
+ test "records who reactivated it" do
+ user = insert(:user)
+
+ {:ok, _} =
+ EmailSuppressions.create_from_bounce(%{
+ email: "[email protected]",
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ assert {:ok, suppression} = EmailSuppressions.reactivate("[email protected]", user)
+ assert suppression.reactivated_by_user_id == user.id
+ assert suppression.reactivated_at
+ end
+ end
+end
diff --git a/test/plausible/mailer_test.exs b/test/plausible/mailer_test.exs
index 48cd2f76d0..1d4d615261 100644
--- a/test/plausible/mailer_test.exs
+++ b/test/plausible/mailer_test.exs
@@ -30,4 +30,101 @@ defmodule Plausible.MailerTest do
assert email.from == mailer_email
end
end
+
+ describe "suppression" do
+ @describetag :ee_only
+
+ test "refuses to send to a suppressed address" do
+ user = insert(:user, email: "[email protected]")
+
+ {:ok, _} =
+ Plausible.EmailSuppressions.create_from_bounce(%{
+ email: user.email,
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ email = PlausibleWeb.Email.welcome_email(user)
+ assert {:error, :suppressed} = Plausible.Mailer.send(email)
+
+ refute_delivered_email(email)
+ end
+
+ test "sends normally once the address is no longer suppressed" do
+ user = insert(:user, email: "[email protected]")
+ reviewer = insert(:user)
+
+ {:ok, _} =
+ Plausible.EmailSuppressions.create_from_bounce(%{
+ email: user.email,
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ {:ok, _} = Plausible.EmailSuppressions.reactivate(user.email, reviewer)
+
+ email = PlausibleWeb.Email.welcome_email(user)
+ assert :ok = Plausible.Mailer.send(email)
+
+ assert_delivered_email(email)
+ end
+
+ test "still sends priority-stream e-mails to a suppressed address" do
+ address = "[email protected]"
+
+ {:ok, _} =
+ Plausible.EmailSuppressions.create_from_bounce(%{
+ email: address,
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ email = PlausibleWeb.Email.password_reset_email(address, "http://example.com/reset")
+ assert :ok = Plausible.Mailer.send(email)
+
+ assert_delivered_email(email)
+ end
+
+ test "does not send a non-priority e-mail to a suppressed address, even alongside a priority one" do
+ address = "[email protected]"
+
+ {:ok, _} =
+ Plausible.EmailSuppressions.create_from_bounce(%{
+ email: address,
+ reason: :hard_bounce,
+ source: :webhook
+ })
+
+ base_email = PlausibleWeb.Email.welcome_email(insert(:user, email: address))
+
+ priority_email =
+ PlausibleWeb.Email.password_reset_email(address, "http://example.com/reset")
+
+ assert {:error, :suppressed} = Plausible.Mailer.send(base_email)
+ assert :ok = Plausible.Mailer.send(priority_email)
+
+ refute_delivered_email(base_email)
+ assert_delivered_email(priority_email)
+ end
+
+ test "crashes rather than silently under-checking when `to` has more than one address" do
+ email =
+ Bamboo.Email.new_email(
+ )
+
+ assert_raise RuntimeError, ~r/only supports a single `to` recipient/, fn ->
+ Plausible.Mailer.send(email)
+ end
+ end
+
+ test "crashes rather than silently under-checking when `to` is empty" do
+ email = Bamboo.Email.new_email(from: "[email protected]", to: [])
+
+ assert_raise RuntimeError, ~r/only supports a single `to` recipient/, fn ->
+ Plausible.Mailer.send(email)
+ end
+ end
+ end
end