Domains

Email is refused unless its sender address belongs to a verified domain of the organization. There is no implicit from-address to fall back on.

The domain object

{
  "id": "…",
  "domain": "mail.example.com",
  "verification_status": "verified",
  "created_at": "…",
  "verified_at": "…",
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_notifyzr.mail.example.com",
      "value": "notifyzr-verification=…",
      "status": "found"
    },
    {
      "purpose": "dkim",
      "type": "TXT",
      "name": "nz1._domainkey.mail.example.com",
      "value": "v=DKIM1; k=rsa; p=…",
      "status": "found"
    },
    {
      "purpose": "spf",
      "type": "TXT",
      "name": "mail.example.com",
      "value": "v=spf1 include:… ~all",
      "status": "missing"
    }
  ]
}

verification_status is pending, verified or failed. Each record's status is found, missing or unknown — unknown means the lookup itself did not answer, which is not the same as the record being absent.

Add a domain

POST /v1/domains

curl -X POST http://api.localhost/v1/domains \
  -H "X-API-Key: $NOTIFYZR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "mail.example.com" }'

The response carries the three DNS records to publish. A subdomain you control is the usual choice.

Verify

POST /v1/domains/{id}/verify

Re-resolves the records and updates the status. Ownership alone decides it — a domain does not fail because an SPF include moved, though the record's own status will say so.

Emits domain.verified on a promotion.

List and delete

GET    /v1/domains
DELETE /v1/domains/{id}

Deleting a domain stops sending from its addresses. Messages already sent keep their attribution until the row is pruned.

Verification is re-checked for you

A daily sweep re-resolves the records of every pending and verified domain, least recently checked first. Three rules govern it, and they are the difference between a useful check and an outage that silently stops an instance sending:

• A failed lookup is distinguished from an absent record. A resolver outage would otherwise read as every domain on the instance losing its records within the same minute. Such a run changes nothing.
• A verified domain is demoted only after several consecutive misses (three by default), and the counter is cleared the moment the record resolves again.
• A pending domain is only ever promoted, never demoted — pending means "not published yet", which is not a fault to report. failed domains are not swept at all: recovering one is the /verify call, not the sweep.

On a demotion the organization's owners and admins are emailed and domain.verification_lost is emitted — which is how an API-first integration hears about a domain failing without watching the dashboard. There is no notification table: the status flip is the de-duplication.