Mailglass.Deliverability.Result (Mailglass v1.0.0)

Copy Markdown View Source

Shared plain-data contract for mix mail.doctor runtime results.

The result shape is the single source of truth for both human and JSON output. Formatters must consume this data directly rather than scraping text.

Status Contract

Findings use a closed status set:

  • :pass
  • :warn
  • :fail
  • :cannot_verify

:cannot_verify is a first-class outcome. Resolver uncertainty, missing explicit DKIM selectors, and malformed DNS answers must stay visible as data instead of being coerced into :fail.

Summary

Types

facts()
finding()
resolver_error()
status()
summary()
t()

Functions

empty_facts()
empty_summary()
new(opts)
schema_version()
status?(status)
statuses()
summary(findings)

Types

facts()

@type facts() :: %{spf: map(), dkim: map(), dmarc: map(), mx: map(), bimi: map()}

finding()

@type finding() :: %{
  :area => atom(),
  :check => atom(),
  :status => status(),
  :title => String.t(),
  :why_it_matters => String.t(),
  :observed => String.t(),
  :remediation => String.t(),
  optional(:evidence) => term()
}

resolver_error()

@type resolver_error() :: %{
  :lookup => :txt | :mx | :cname,
  :domain => String.t(),
  :reason => atom(),
  optional(:context) => map()
}

status()

@type status() :: :pass | :warn | :fail | :cannot_verify

summary()

@type summary() :: %{
  pass: non_neg_integer(),
  warn: non_neg_integer(),
  fail: non_neg_integer(),
  cannot_verify: non_neg_integer()
}

t()

@type t() :: %{
  schema_version: pos_integer(),
  domain: String.t(),
  dkim_selectors: [String.t()],
  summary: summary(),
  findings: [finding()],
  facts: facts(),
  resolver_errors: [resolver_error()]
}

Functions

empty_facts()

@spec empty_facts() :: %{spf: %{}, dkim: %{}, dmarc: %{}, mx: %{}, bimi: %{}}

empty_summary()

@spec empty_summary() :: %{pass: 0, warn: 0, fail: 0, cannot_verify: 0}

new(opts)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, term()}

schema_version()

@spec schema_version() :: 1

status?(status)

@spec status?(term()) :: boolean()

statuses()

@spec statuses() :: [status(), ...]

summary(findings)

@spec summary([finding()]) :: summary()