EmailDomainResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hail-so/json-schema/hail-so-email-domain-response-schema.json",
  "title": "EmailDomainResponse",
  "description": "Read view for an email domain.\n\nThe inbound-action fields (``inbound_enabled``, ``forward_to``,\n``forward_rate_per_hour``) surface what the row has configured for\nincoming mail.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hail-so-openapi.json#/components/schemas/EmailDomainResponse",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "title": "Id",
      "description": "Unique identifier for this email domain."
    },
    "organization_id": {
      "type": "string",
      "format": "uuid",
      "title": "Organization Id",
      "description": "Organization that owns this domain."
    },
    "kind": {
      "type": "string",
      "enum": [
        "hail_mail",
        "custom"
      ],
      "title": "Kind",
      "description": "'hail_mail' (Hail-hosted address) or 'custom' (your own domain)."
    },
    "domain": {
      "type": "string",
      "title": "Domain",
      "description": "The DNS domain mail is sent from."
    },
    "local_prefix_user": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Local Prefix User",
      "description": "User local-part prefix for a hail_mail address. Null for kind='custom'."
    },
    "local_prefix_org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Local Prefix Org",
      "description": "Org local-part prefix for a hail_mail address. Null for kind='custom'."
    },
    "verification_status": {
      "type": "string",
      "enum": [
        "pending",
        "verified",
        "failed"
      ],
      "title": "Verification Status",
      "description": "'pending' (not yet verified), 'verified' (ready to send), or 'failed'."
    },
    "dns_records": {
      "items": {
        "$ref": "#/$defs/DnsRecordSchema"
      },
      "type": "array",
      "title": "Dns Records",
      "description": "DNS records (DKIM, MAIL FROM MX, SPF) the tenant must publish to verify this domain."
    },
    "mail_from_domain": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mail From Domain",
      "description": "Custom MAIL FROM domain, if configured. Null when using the provider default."
    },
    "mail_from_status": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Mail From Status",
      "description": "Verification status of the custom MAIL FROM domain, if one is configured. Secondary to verification_status."
    },
    "provider": {
      "type": "string",
      "title": "Provider",
      "description": "Email sending provider for this domain (currently always 'ses')."
    },
    "verified_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Verified At",
      "description": "When the domain became verified, ISO 8601 timestamp. Null until it is."
    },
    "inbound_enabled": {
      "type": "boolean",
      "title": "Inbound Enabled",
      "description": "Whether this domain accepts and forwards inbound mail.",
      "default": false
    },
    "forward_to": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Forward To",
      "description": "Email addresses inbound mail is forwarded to, if inbound is enabled."
    },
    "forward_rate_per_hour": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Forward Rate Per Hour",
      "description": "Configured cap on forwarded messages per hour, if set."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At",
      "description": "When this domain was added, ISO 8601 timestamp."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "title": "Updated At",
      "description": "When this domain was last modified, ISO 8601 timestamp."
    },
    "receive_ready": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Receive Ready",
      "description": "True when the domain's published MX points at Hail's inbound host. Only populated by POST /{id}/verify on custom domains; null everywhere else."
    }
  },
  "type": "object",
  "required": [
    "id",
    "organization_id",
    "kind",
    "domain",
    "local_prefix_user",
    "local_prefix_org",
    "verification_status",
    "dns_records",
    "mail_from_domain",
    "provider",
    "verified_at",
    "created_at",
    "updated_at"
  ],
  "$defs": {
    "DnsRecordSchema": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "DNS record name/host to publish (e.g. a CNAME's subdomain)."
        },
        "value": {
          "type": "string",
          "title": "Value",
          "description": "DNS record value to publish (e.g. a CNAME target or TXT content)."
        },
        "type": {
          "type": "string",
          "enum": [
            "CNAME",
            "MX",
            "TXT"
          ],
          "title": "Type",
          "description": "DNS record type: 'CNAME' (DKIM), 'MX' (MAIL FROM), or 'TXT' (SPF).",
          "default": "CNAME"
        },
        "priority": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Priority",
          "description": "MX priority. Only present for type='MX'; null otherwise."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "required": [
        "name",
        "value"
      ],
      "title": "DnsRecordSchema",
      "description": "One DNS record the tenant must publish for a sending domain.\n\nCovers DKIM CNAMEs, MAIL FROM MX, and SPF TXT records."
    }
  }
}