The DNS records for a custom domain

email.domain.records

GET/api/v1/households/{household_id}/queries/email.domain.records

Query
Rigel runs it

A custom domain's state in words and the DNS records its owner must add, each with whether it checks out. Returns null when there is no such domain. Use email.domain.check to have them checked again.

Parameters#

The DNS records for a custom domain: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`email_domain_id`querystringrequired	The domain.

Response#

200 The answer.

The DNS records for a custom domain: response fields
Field	Description
`domain`object or nullrequired	The domain, or null when it doesn't exist.
`domain.id`stringrequired	A email domain ID, such as emd_01JC0000000000000000000000.
`domain.domain`stringrequired	The domain.
`domain.state`one of: pending, receiving, sending, ready, brokenrequired	The custom domain's state: pending (nothing verified), receiving (mail addressed to it has arrived), sending (verified for sending), ready (both work), broken (a record that checked out stopped checking out).
`domain.state_in_words`stringrequired	What the state means, in words.
`domain.checked_at`string (date-time) or nullrequired	When it was last checked, or null.
`domain.records`array of objectsrequired
`domain.records[].id`stringrequired	A email domain record ID, such as emk_01JC0000000000000000000000.
`domain.records[].purpose`one of: dkim, spf, dmarcrequired	What it is for: dkim, spf or dmarc.
`domain.records[].type`one of: CNAME, TXTrequired	The DNS record type.
`domain.records[].name`stringrequired	The record's full name.
`domain.records[].value`stringrequired	What it must contain.
`domain.records[].state`one of: unchecked, ok, missing, wrongrequired	What the last check of the DNS record found: unchecked, ok, missing or wrong.
`domain.records[].state_in_words`stringrequired	Whether it checks out, in words.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

The DNS records for a custom domain: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Check a custom domain's DNS records

Each record says what to add at the domain's host, and whether the last check found it.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.domain.records?email_domain_id=emd_01M6V9CSQ63D47MKP7KG4FEBDJ' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.domain.records?email_domain_id=emd_01M6V9CSQ63D47MKP7KG4FEBDJ", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/queries/email.domain.records?email_domain_id=emd_01M6V9CSQ63D47MKP7KG4FEBDJ HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSRWJR3C4NTMJWVZ3A8T

{
  "domain": {
    "id": "emd_01M6V9CSQ63D47MKP7KG4FEBDJ",
    "domain": "okafors.example.com",
    "state": "ready",
    "state_in_words": "Ready: receiving and sending both work.",
    "checked_at": "2026-11-07T15:17:52.497Z",
    "records": [
      {
        "id": "emk_01M6V9CSQ6RCFTEVP7WVA5GRA8",
        "purpose": "dmarc",
        "type": "TXT",
        "name": "_dmarc.okafors.example.com",
        "value": "v=DMARC1; p=none;",
        "state": "ok",
        "state_in_words": "Checks out."
      },
      {
        "id": "emk_01M6V9CSQ6S4RHTRP75A5KF0EV",
        "purpose": "dkim",
        "type": "CNAME",
        "name": "4i66eswkutos6cmaty5d500juyjzrfpj._domainkey.okafors.example.com",
        "value": "4i66eswkutos6cmaty5d500juyjzrfpj.dkim.amazonses.com",
        "state": "ok",
        "state_in_words": "Checks out."
      },
      {
        "id": "emk_01M6V9CSQ6T1ZF8PP7J2A1Z3AZ",
        "purpose": "dkim",
        "type": "CNAME",
        "name": "5fcpz69x0fiifk0b9nt2kbjro5x4z6bo._domainkey.okafors.example.com",
        "value": "5fcpz69x0fiifk0b9nt2kbjro5x4z6bo.dkim.amazonses.com",
        "state": "ok",
        "state_in_words": "Checks out."
      },
      {
        "id": "emk_01M6V9CSQ6WBXPQHP7GZE0YAAF",
        "purpose": "dkim",
        "type": "CNAME",
        "name": "420ws4spo1ukfobreeqdn73jwhz5iikf._domainkey.okafors.example.com",
        "value": "420ws4spo1ukfobreeqdn73jwhz5iikf.dkim.amazonses.com",
        "state": "ok",
        "state_in_words": "Checks out."
      },
      {
        "id": "emk_01M6V9CSQ6ZHVD2YP7Z4DQ0SZX",
        "purpose": "spf",
        "type": "TXT",
        "name": "okafors.example.com",
        "value": "v=spf1 include:amazonses.com ~all",
        "state": "ok",
        "state_in_words": "Checks out."
      }
    ]
  }
}

For Rigel#

Rigel's tool for this query is email_domain_records. Rigel runs this on its own, then says what it did. The agent guide has the rest.