Skip to content

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

Handle Postmark's SubscriptionChange webhook to suppress unsubscribes (#6708)

Adamfe43fd78feca
diff --git a/lib/plausible/email_suppressions.ex b/lib/plausible/email_suppressions.ex
index 3dc2cb6281..442ef10188 100644
--- a/lib/plausible/email_suppressions.ex
+++ b/lib/plausible/email_suppressions.ex
@@ -110,6 +110,19 @@ defmodule Plausible.EmailSuppressions do
where(query, [s], ilike(s.email, ^"%#{search}%"))
end
+ @doc """
+ Records (or refreshes) a suppression originating from Postmark's
+ Subscription Change webhook (an address unsubscribing).
+ """
+ @spec create_from_unsubscribe(map()) ::
+ {:ok, EmailSuppression.t()} | {:error, Ecto.Changeset.t()}
+ def create_from_unsubscribe(attrs) do
+ attrs
+ |> Map.take([:email, :source, :details])
+ |> Map.put(:reason, :unsubscribe)
+ |> upsert()
+ end
+
@doc """
Lifts a suppression after manual review, recording who did it.
Encapsulates suppression remote deletion at Postmark - can't be done for spam complaints.
diff --git a/lib/plausible/postmark.ex b/lib/plausible/postmark.ex
index e17e923ffe..84931f4898 100644
--- a/lib/plausible/postmark.ex
+++ b/lib/plausible/postmark.ex
@@ -17,7 +17,8 @@ defmodule Plausible.Postmark do
"HardBounce" => :hard_bounce,
"BadEmailAddress" => :bad_email_address,
"Blocked" => :blocked,
- "SpamNotification" => :spam_notification
+ "SpamNotification" => :spam_notification,
+ "Unsubscribe" => :unsubscribe
}
@spec suppressing_reason(String.t()) :: {:ok, atom()} | :error
diff --git a/lib/plausible_web/controllers/api/postmark_controller.ex b/lib/plausible_web/controllers/api/postmark_controller.ex
index 786264d6f5..aaee534f60 100644
--- a/lib/plausible_web/controllers/api/postmark_controller.ex
+++ b/lib/plausible_web/controllers/api/postmark_controller.ex
@@ -1,7 +1,7 @@
defmodule PlausibleWeb.Api.PostmarkController do
@moduledoc """
- Receives Postmark's Bounce and SpamComplaint webhooks and records
- addresses in `Plausible.EmailSuppressions`.
+ Receives Postmark's Bounce, SpamComplaint and SubscriptionChange webhooks
+ and records addresses in `Plausible.EmailSuppressions`.
See https://postmarkapp.com/developer/webhooks/webhooks-overview
"""
@@ -35,6 +35,22 @@ defmodule PlausibleWeb.Api.PostmarkController do
ok(conn)
end
+ def webhook(
+ conn,
+ %{
+ "RecordType" => "SubscriptionChange",
+ "SuppressSending" => true,
+ "SuppressionReason" => "ManualSuppression"
+ } = params
+ ) do
+ params
+ |> unsubscribe_attrs()
+ |> Plausible.EmailSuppressions.create_from_unsubscribe()
+ |> log_on_error(params)
+
+ ok(conn)
+ end
+
def webhook(conn, params) do
Sentry.capture_message("Received unexpected Postmark webhook record type",
extra: %{record_type: params["RecordType"], params: params}
@@ -54,6 +70,14 @@ defmodule PlausibleWeb.Api.PostmarkController do
}
end
+ defp unsubscribe_attrs(params) do
+ %{
+ email: params["Recipient"],
+ source: :webhook,
+ details: "Unsubscribed via Postmark (origin: #{params["Origin"]})"
+ }
+ end
+
defp log_on_error({:ok, _suppression}, _params), do: :ok
defp log_on_error({:error, changeset}, params) do
diff --git a/test/plausible/email_suppressions_test.exs b/test/plausible/email_suppressions_test.exs
index 497fe6cf7f..f2e9b19122 100644
--- a/test/plausible/email_suppressions_test.exs
+++ b/test/plausible/email_suppressions_test.exs
@@ -237,6 +237,46 @@ defmodule Plausible.EmailSuppressionsTest do
end
end
+ describe "create_from_unsubscribe/1" do
+ test "sets reason to :unsubscribe" do
+ {:ok, suppression} =
+ EmailSuppressions.create_from_unsubscribe(%{
+ email: "[email protected]",
+ source: :webhook,
+ details: "Unsubscribed via Postmark (origin: Recipient)"
+ })
+
+ assert suppression.reason == :unsubscribe
+ assert suppression.details == "Unsubscribed via Postmark (origin: Recipient)"
+ assert EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "an unsubscribe 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_unsubscribe(%{
+ email: "[email protected]",
+ source: :webhook
+ })
+
+ assert EmailSuppressions.suppressed?("[email protected]")
+ assert suppression.reason == :unsubscribe
+ 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)
diff --git a/test/plausible/postmark_test.exs b/test/plausible/postmark_test.exs
index cefbfcb516..182e3c6f78 100644
--- a/test/plausible/postmark_test.exs
+++ b/test/plausible/postmark_test.exs
@@ -12,6 +12,7 @@ defmodule Plausible.PostmarkTest do
assert Postmark.suppressing_reason("BadEmailAddress") == {:ok, :bad_email_address}
assert Postmark.suppressing_reason("Blocked") == {:ok, :blocked}
assert Postmark.suppressing_reason("SpamNotification") == {:ok, :spam_notification}
+ assert Postmark.suppressing_reason("Unsubscribe") == {:ok, :unsubscribe}
end
test "does not map transient bounce types" do
diff --git a/test/plausible_web/controllers/api/postmark_controller_test.exs b/test/plausible_web/controllers/api/postmark_controller_test.exs
index 89fb89f094..0fb9f80ce5 100644
--- a/test/plausible_web/controllers/api/postmark_controller_test.exs
+++ b/test/plausible_web/controllers/api/postmark_controller_test.exs
@@ -110,6 +110,19 @@ defmodule PlausibleWeb.Api.PostmarkControllerTest do
refute EmailSuppressions.suppressed?("[email protected]")
end
+ test "suppresses on an Unsubscribe bounce type", %{conn: conn} do
+ payload = %{@bounce_payload | "Type" => "Unsubscribe"}
+ conn = post(conn, ~p"/api/postmark/webhook", payload)
+
+ assert json_response(conn, 200) == %{}
+ assert EmailSuppressions.suppressed?("[email protected]")
+
+ suppression =
+ Plausible.Repo.get_by!(Plausible.EmailSuppression, email: "[email protected]")
+
+ assert suppression.reason == :unsubscribe
+ end
+
test "records the Postmark bounce details", %{conn: conn} do
post(conn, ~p"/api/postmark/webhook", @bounce_payload)
@@ -147,6 +160,56 @@ defmodule PlausibleWeb.Api.PostmarkControllerTest do
end
end
+ describe "SubscriptionChange webhook" do
+ @subscription_change_payload %{
+ "RecordType" => "SubscriptionChange",
+ "MessageID" => "883953f4-6105-42a2-a16a-77a8eac79483",
+ "ServerID" => 23,
+ "MessageStream" => "outbound",
+ "ChangedAt" => "2026-11-05T16:33:54.9070259Z",
+ "Recipient" => "[email protected]",
+ "Origin" => "Recipient",
+ "SuppressSending" => true,
+ "SuppressionReason" => "ManualSuppression"
+ }
+
+ test "suppresses the address when it unsubscribed", %{conn: conn} do
+ conn = post(conn, ~p"/api/postmark/webhook", @subscription_change_payload)
+
+ assert json_response(conn, 200) == %{}
+ assert EmailSuppressions.suppressed?("[email protected]")
+
+ suppression =
+ Plausible.Repo.get_by!(Plausible.EmailSuppression, email: "[email protected]")
+
+ assert suppression.reason == :unsubscribe
+ assert suppression.source == :webhook
+ end
+
+ test "ignores a reactivation (SuppressSending: false)", %{conn: conn} do
+ payload = %{
+ @subscription_change_payload
+ | "SuppressSending" => false,
+ "SuppressionReason" => nil
+ }
+
+ conn = post(conn, ~p"/api/postmark/webhook", payload)
+
+ assert json_response(conn, 200) == %{}
+ refute EmailSuppressions.suppressed?("[email protected]")
+ end
+
+ test "ignores HardBounce/SpamComplaint reasons, already handled by their own webhooks", %{
+ conn: conn
+ } do
+ payload = %{@subscription_change_payload | "SuppressionReason" => "HardBounce"}
+ conn = post(conn, ~p"/api/postmark/webhook", payload)
+
+ assert json_response(conn, 200) == %{}
+ refute EmailSuppressions.suppressed?("[email protected]")
+ end
+ end
+
describe "other webhook types" do
setup %{test_pid: test_pid} do
Plausible.Test.Support.Sentry.setup(test_pid)