Mailglass.Suppression (Mailglass v1.0.0)

Public preflight facade for suppression checks (SEND-04).

Thin wrapper over Mailglass.SuppressionStore.check/2 configured via:

config :mailglass, :suppression_store, Mailglass.SuppressionStore.Ecto  # default
config :mailglass, :suppression_store, Mailglass.SuppressionStore.ETS   # test-speed

Return shape

:ok when the recipient is not suppressed
{:error, %Mailglass.SuppressedError{type: scope}} on a suppression hit

Telemetry

Single-emit [:mailglass, :outbound, :suppression, :stop] with:

Measurements: %{duration_us: integer()}
Metadata: %{hit: boolean(), tenant_id: String.t()}

No PII — neither address nor stream appears in metadata. Context on the %SuppressedError{} carries tenant_id + stream only (stream is enum-narrow, not recipient-identifying).

Summary

Functions

check_before_send(msg)

Pre-send suppression check. Returns :ok when allowed, {:error, %SuppressedError{}} when blocked.

remove(id, opts \\ [])

Removes a suppression entry unless the reason is permanently non-removable.

Functions

check_before_send(msg)

(since 0.1.0)

@spec check_before_send(Mailglass.Message.t()) ::
  :ok | {:error, Mailglass.SuppressedError.t()}

Pre-send suppression check. Returns :ok when allowed, {:error, %SuppressedError{}} when blocked.

Extracts the primary recipient from msg.swoosh_email.to and delegates to the configured SuppressionStore implementation.

remove(id, opts \\ [])

(since 0.2.0)

@spec remove(
  Ecto.UUID.t(),
  keyword()
) ::
  {:ok, Mailglass.Suppression.Entry.t()}
  | {:error,
     Mailglass.SendError.t() | Ecto.Changeset.t() | :invalid_id | :not_found}

Removes a suppression entry unless the reason is permanently non-removable.

Complaint and unsubscribe rows remain durable compliance controls and return a structured rejection error instead of deleting the row.