> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thepurplebox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify a Domain

> Trigger verification of DNS records for a domain identity.

### Headers

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

### Query Parameters

<ParamField query="value" type="string" required>
  The domain name to verify (e.g., `yourdomain.com`).
</ParamField>

### Response

<ResponseField name="status" type="number">
  HTTP status code. Returns `200` when the verification check is triggered successfully.
</ResponseField>

<ResponseField name="message" type="string">
  A human-readable message describing the result of the verification check.
</ResponseField>

<ResponseField name="data" type="object">
  Contains the updated domain verification status after the check.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique identifier for the domain identity.
    </ResponseField>

    <ResponseField name="value" type="string">
      The domain name that was verified.
    </ResponseField>

    <ResponseField name="team_id" type="string">
      The team ID that owns this domain identity.
    </ResponseField>

    <ResponseField name="status" type="string">
      Updated status of the domain after verification. Possible values: `not_started`, `pending`, `success`, `failed`, `temporary_failure`.
    </ResponseField>

    <ResponseField name="identity_type" type="string">
      Type of identity. Always `domain` for domain identities.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the domain identity was created.
    </ResponseField>

    <ResponseField name="verified_at" type="string | null">
      ISO 8601 timestamp when the domain was verified. Null if not yet verified.
    </ResponseField>

    <ResponseField name="attributes" type="object">
      DNS configuration attributes with updated verification statuses.

      <Expandable title="properties">
        <ResponseField name="dkim_attributes" type="object">
          DKIM record configuration with updated verification status.

          <Expandable title="properties">
            <ResponseField name="name" type="string">
              The DNS record name for the DKIM selector.
            </ResponseField>

            <ResponseField name="record_type" type="string">
              The DNS record type. Always `TXT` for DKIM records.
            </ResponseField>

            <ResponseField name="value" type="string">
              The DKIM public key value.
            </ResponseField>

            <ResponseField name="ttl" type="string">
              Time to Live for the DNS record.
            </ResponseField>

            <ResponseField name="status" type="string">
              Updated verification status. Possible values: `not_started`, `pending`, `success`, `failed`.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="mail_from_attributes" type="array">
          Array of DNS records with updated verification statuses.

          <Expandable title="properties">
            <ResponseField name="name" type="string">
              The subdomain name for the mail record.
            </ResponseField>

            <ResponseField name="record_type" type="string">
              The DNS record type.
            </ResponseField>

            <ResponseField name="value" type="string">
              The DNS record value.
            </ResponseField>

            <ResponseField name="ttl" type="string">
              Time to Live for the DNS record.
            </ResponseField>

            <ResponseField name="status" type="string">
              Updated verification status.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="dmarc_attributes" type="object">
          DMARC record configuration with updated verification status.

          <Expandable title="properties">
            <ResponseField name="name" type="string">
              The DNS record name for DMARC.
            </ResponseField>

            <ResponseField name="record_type" type="string">
              The DNS record type.
            </ResponseField>

            <ResponseField name="value" type="string">
              The DMARC policy value.
            </ResponseField>

            <ResponseField name="ttl" type="string">
              Time to Live for the DNS record.
            </ResponseField>

            <ResponseField name="status" type="string">
              Updated verification status.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="verification_status" type="string">
          Overall verification status after the check. Possible values: `not_started`, `pending`, `success`, `failed`, `temporary_failure`.
        </ResponseField>

        <ResponseField name="verified_for_sending_status" type="boolean">
          Indicates whether the domain is verified and ready to send emails. Returns `true` when all DNS records are verified.
        </ResponseField>

        <ResponseField name="error_type" type="string">
          Error type if verification fails. Empty string when no errors are present.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="last_status_checked_at" type="string">
      ISO 8601 timestamp of the verification check (updated to current time).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
      "status": 200,
      "message": "verification triggered successfully.",
      "data": {
          "id": "xxxxx",
          "value": "yourdomain.com",
          "team_id": "xxxxx",
          "status": "success",
          "identity_type": "domain",
          "created_at": "2025-11-21T10:23:14.737725Z",
          "verified_at": "2025-11-21T10:30:45.123456Z",
          "attributes": {
              "dkim_attributes": {
                  "name": "thepurplebox._domainkey.yourdomain",
                  "record_type": "TXT",
                  "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsBL1UV+VVUqIlNrkhBBC...xxxxx",
                  "ttl": "auto",
                  "status": "success"
              },
              "mail_from_attributes": [
                  {
                      "name": "send.yourdomain",
                      "record_type": "TXT",
                      "value": "xxxxx",
                      "ttl": "60",
                      "status": "success"
                  },
                  {
                      "name": "bounce.yourdomain",
                      "record_type": "CNAME",
                      "value": "xxxx",
                      "ttl": "60",
                      "status": "success"
                  }
              ],
              "dmarc_attributes": {
                  "name": "_dmarc",
                  "record_type": "TXT",
                  "value": "v=DMARC1;p=none;",
                  "ttl": "auto",
                  "status": "success"
              },
              "verification_status": "success",
              "verified_for_sending_status": true,
              "error_type": ""
          },
          "last_status_checked_at": "2025-11-21T10:30:45.123456Z"
      }
  }
  ```
</ResponseExample>