{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/sendly-now/json-schema/sendly-now-deliverability-diagnosis-v1-schema.json",
  "title": "DeliverabilityDiagnosisV1",
  "description": "A composed answer to why mail from one domain may not be arriving: its DNS identity, the project's recent delivery outcomes, one address's suppression state, and the findings drawn from them.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/sendly-now-deliverability-api-openapi.yml#/components/schemas/DeliverabilityDiagnosisV1",
  "properties": {
    "address": {
      "type": [
        "string",
        "null"
      ]
    },
    "checked_at": {
      "format": "date-time",
      "type": "string"
    },
    "domain": {
      "type": "string"
    },
    "findings": {
      "description": "What is wrong, worst first. An empty array means nothing here explains a delivery problem.",
      "items": {
        "$ref": "#/$defs/DeliverabilityFindingV1"
      },
      "type": "array"
    },
    "identity": {
      "$ref": "#/$defs/DeliverabilityIdentityV1"
    },
    "recent_delivery": {
      "$ref": "#/$defs/DeliverabilityRecentDeliveryV1"
    },
    "suppression": {
      "$ref": "#/$defs/DeliverabilitySuppressionV1"
    }
  },
  "required": [
    "domain",
    "address",
    "checked_at",
    "identity",
    "suppression",
    "recent_delivery",
    "findings"
  ],
  "type": "object",
  "$defs": {
    "DeliverabilityFindingSeverityV1": {
      "description": "`blocking`: mail from this domain cannot be delivered as configured. `degraded`: it delivers, but inbox placement or sender reputation is at risk. `info`: worth knowing, nothing to fix.",
      "enum": [
        "blocking",
        "degraded",
        "info"
      ],
      "type": "string"
    },
    "DeliverabilityFindingV1": {
      "description": "One diagnosed problem, with its fix.",
      "properties": {
        "code": {
          "description": "Stable identifier for this finding, e.g. `domain_not_verified`. Branch on this, not on `summary`.",
          "type": "string"
        },
        "remedy": {
          "description": "What to do about it.",
          "type": "string"
        },
        "severity": {
          "$ref": "#/$defs/DeliverabilityFindingSeverityV1"
        },
        "summary": {
          "description": "What is wrong, in one sentence.",
          "type": "string"
        }
      },
      "required": [
        "code",
        "severity",
        "summary",
        "remedy"
      ],
      "type": "object"
    },
    "DeliverabilityIdentityV1": {
      "description": "The sending identity's DNS health, as last refreshed.",
      "properties": {
        "dkim_status": {
          "description": "DKIM signing. This is the one that decides whether Sendly will send from the domain at all.",
          "enum": [
            "NOT_CHECKED",
            "PENDING",
            "VERIFIED",
            "FAILED",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "dmarc_status": {
          "description": "The DMARC policy published at `_dmarc.<domain>`.",
          "enum": [
            "NOT_CHECKED",
            "PENDING",
            "VERIFIED",
            "FAILED",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "last_checked_at": {
          "description": "When the DNS refresh job last looked. These statuses are a CACHE, not a live lookup.",
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "mail_from_domain": {
          "type": [
            "string",
            "null"
          ]
        },
        "mail_from_domain_status": {
          "description": "Raw SES `CustomMailFromStatus` (`Pending`/`Success`/`Failed`/`TemporaryFailure`), or `NotConfigured`. `Failed` means SES silently fell back to `amazonses.com`, which is why the value is reported rather than folded into a boolean.",
          "type": [
            "string",
            "null"
          ]
        },
        "mx_status": {
          "description": "Inbound receiving only. Null unless the domain has receiving enabled.",
          "enum": [
            "NOT_CHECKED",
            "PENDING",
            "VERIFIED",
            "FAILED",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "registered": {
          "description": "Whether this project has a domain record at all. False makes every other field null.",
          "type": "boolean"
        },
        "spf_status": {
          "description": "SPF alignment for the sending identity.",
          "enum": [
            "NOT_CHECKED",
            "PENDING",
            "VERIFIED",
            "FAILED",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "verified": {
          "type": "boolean"
        }
      },
      "required": [
        "registered",
        "verified",
        "dkim_status",
        "spf_status",
        "dmarc_status",
        "mx_status",
        "mail_from_domain",
        "mail_from_domain_status",
        "last_checked_at"
      ],
      "type": "object"
    },
    "DeliverabilityRecentDeliveryV1": {
      "description": "Delivery outcomes over the requested window.",
      "properties": {
        "bounce_rate": {
          "description": "Bounced ÷ sent (0–1), or null when nothing was sent in the window.",
          "type": [
            "number",
            "null"
          ]
        },
        "bounced": {
          "type": "integer"
        },
        "complained": {
          "type": "integer"
        },
        "complaint_rate": {
          "type": [
            "number",
            "null"
          ]
        },
        "delivered": {
          "type": "integer"
        },
        "failed": {
          "type": "integer"
        },
        "scope": {
          "description": "PROJECT-WIDE, not per-domain, and said so rather than implied. `Email` has no sending-domain column, so narrowing these counters to one domain would mean a scan over every row the project has ever sent. A project that sends from one domain — most of them — can read these as that domain's.",
          "enum": [
            "project"
          ],
          "type": "string"
        },
        "sent": {
          "type": "integer"
        },
        "window_days": {
          "type": "integer"
        }
      },
      "required": [
        "window_days",
        "scope",
        "sent",
        "delivered",
        "bounced",
        "complained",
        "failed",
        "bounce_rate",
        "complaint_rate"
      ],
      "type": "object"
    },
    "DeliverabilitySuppressionV1": {
      "description": "Null unless the request named an `address`.",
      "properties": {
        "reason": {
          "enum": [
            "HARD_BOUNCE",
            "COMPLAINT",
            "MANUAL",
            "UNSUBSCRIBE",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "enum": [
            "SES_WEBHOOK",
            "API",
            "DASHBOARD",
            null
          ],
          "type": [
            "string",
            "null"
          ]
        },
        "suppressed": {
          "type": "boolean"
        },
        "suppressed_at": {
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "suppressed",
        "reason",
        "source",
        "suppressed_at"
      ],
      "type": [
        "object",
        "null"
      ]
    }
  }
}