Domain

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/openmail-sh/json-schema/openmail-sh-domain-schema.json",
  "title": "Domain",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/openmail-sh-openapi.json#/components/schemas/Domain",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "id": {
      "type": "string",
      "description": "OpenMail domain ID"
    },
    "domain": {
      "type": "string",
      "description": "The domain or subdomain, e.g. `example.com` or `agent-mail.example.com`."
    },
    "podId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pod this domain is scoped to, so only inboxes in that pod can use it, or null for an account-wide domain."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verifying",
        "verified",
        "failed",
        "under_review"
      ],
      "description": "`pending` — added, records not yet published. `verifying` — being checked. `verified` — sending and receiving enabled. `failed` — records missing or wrong; publishing them and calling verify again is the fix. `under_review` — flagged as suspicious; DNS setup is blocked until approved."
    },
    "records": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DomainRecord"
      },
      "description": "The DNS records to publish for this domain. Returned even where the values are the same for every customer, so sending infrastructure can change without breaking clients."
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DomainWarning"
      },
      "description": "Problems detected in the domain's DNS that do not block verification but do lose mail. Empty when none. Check this even when `status` is `verified` — every record can be correct and the zone still broken by something else in it."
    },
    "verifiedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "$defs": {
    "DomainRecord": {
      "type": "object",
      "additionalProperties": true,
      "description": "A single DNS record to publish for a custom domain. Publish every record whose `status` is not already `valid`, then the domain verifies automatically within a couple of minutes.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "TXT",
            "CNAME",
            "MX"
          ]
        },
        "name": {
          "type": "string",
          "description": "The record's host, fully qualified, e.g. `_dmarc.agent-mail.example.com`."
        },
        "value": {
          "type": "string",
          "description": "The record value to publish."
        },
        "priority": {
          "type": [
            "integer",
            "null"
          ],
          "description": "MX records only."
        },
        "purpose": {
          "type": "string",
          "enum": [
            "spf",
            "dkim",
            "dmarc",
            "mx",
            "return-path"
          ],
          "description": "What the record is for. Act on this rather than inferring from record shape: SPF must be merged into any the owner already has rather than replacing it, a DMARC policy at an apex can override the owner's own, and an apex MX takes over all their inbound mail."
        },
        "status": {
          "type": "string",
          "enum": [
            "missing",
            "invalid",
            "valid"
          ],
          "description": "Whether this individual record is published and correct as of the last check. `missing` — not found yet. `invalid` — found but wrong. `valid` — published and correct. Shows which records are still outstanding, not only whether the whole domain passed."
        }
      }
    },
    "DomainWarning": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "competing_mx"
          ],
          "description": "`competing_mx` — another MX record is published at the same or a more preferred priority than ours, so senders split the domain's inbound mail between us and a server that does not know its inboxes. Part of the mail bounces `550` while every record shows `valid`. Fix: remove the other MX, or give it a higher priority number than ours."
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation and fix, safe to show to the domain owner."
        },
        "hosts": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The competing MX hosts, lowercase, without trailing dot."
        }
      }
    }
  }
}