Namespace and behaviour for the mailglass error hierarchy.

Mailglass ships eight sibling defexception modules, each with a closed :type atom set that acts as a sub-kind discriminator. There is no parent struct — "hierarchy" here means the shared behaviour contract plus the convention that every error struct lives directly under Mailglass.*.

Error Types

• Mailglass.SendError — delivery failure (adapter, render, preflight, serialization)
• Mailglass.TemplateError — HEEx compile, missing assign, undefined helper, inliner
• Mailglass.SignatureError — webhook signature missing, malformed, mismatch, stale
• Mailglass.SuppressedError — delivery blocked by suppression list
• Mailglass.RateLimitError — rate limit exceeded (domain, tenant, stream)
• Mailglass.ConfigError — configuration missing, invalid, conflicting, optional-dep absent
• Mailglass.EventLedgerImmutableError — SQLSTATE 45A01 translation (D-06, Phase 2)
• Mailglass.TenancyError — tenant context not stamped on the current process (Phase 2)

Pattern Matching

Always match on the struct module and :type field — never on :message. Message strings are a presentation concern; the closed :type atom set is the stable contract:

case result do
  {:error, %Mailglass.SuppressedError{type: :address}} -> ...
  {:error, %Mailglass.RateLimitError{retry_after_ms: ms}} -> ...
  {:error, %Mailglass.SendError{}} -> ...
end

Serialization

Every error struct derives Jason.Encoder on [:type, :message, :context] only. The :cause field is deliberately excluded to prevent recursive emission of adapter structs that may carry provider payloads with PII.

Closed :type Atom Sets

The closed atom set for each struct is documented in docs/api_stability.md and asserted by Mailglass.ErrorTest against each struct's __types__/0. Adding a value requires a CHANGELOG entry + @since annotation (minor version bump). Removing a value requires a major version bump.