Sending domains

Retrieve a sending domain

GET/v1/sending-domains/{id}

Requires an API key with the domains:read scope. About keys and scopes

Returns one domain, its verification state, and the DNS records it expects.

Path parameters

idstringrequired: uuid

Returns

Returns 200 OK with a SendingDomain in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

domainstringrequired

statusstringrequired

Whether the provider has verified the domain for sending.

one of pending, verified, failed

ownershipStatusstringrequired

Whether proof that you control the domain has been found in DNS.

one of pending, verified

ownershipRecordobjectrequired

The record that proves you control the domain.

5 child attributes

typestringrequired: one of CNAME, TXT, MX
namestringrequired: The full hostname to publish the record at.
valuestringrequired: What the record must contain.
foundstring[]optional: What DNS returned for this name and type at the last check; absent before one.
matchesbooleanoptional: Whether found holds value; absent before a check.

separateOwnershipRecordbooleanrequired

False for a domain added since one-trip setup: ownershipRecord is its DKIM record, listed in dnsRecords with the others. True for older domains, whose ownership TXT is published first and on its own.

provisioningStatusstringrequired

Setup progress at the email provider: awaiting_proof until ownership is shown, then provisioning, provisioned. quarantined: the domain is already set up at the provider by someone else, so nothing sends from it until Kirora support reviews it.

one of awaiting_proof, provisioning, provisioned, quarantined

dnsRecordsobject[]required

The records to publish at your DNS host.

5 child attributes

typestringrequired: one of CNAME, TXT, MX
namestringrequired: The full hostname to publish the record at.
valuestringrequired: What the record must contain.
foundstring[]optional: What DNS returned for this name and type at the last check; absent before one.
matchesbooleanoptional: Whether found holds value; absent before a check.

providerstringrequired

The email provider that sends for the domain.

failureReasonstring | nullrequired

Why verification failed, when it has.

readinessChecksobject | nullrequired

Per-check results from the last verification; null before one.

4 child attributes

identitystringrequired

The sending identity.

one of pending, verified, failed

dkimstringrequired

The DKIM signing records.

one of pending, verified, failed

mailFromstringrequired

The custom MAIL FROM (bounce.) records.

one of pending, verified, failed

dmarcobjectrequired

The DMARC record covering the domain.

4 child attributes

statusstringrequired

Whether a usable DMARC record was found.

one of valid, missing, invalid, unknown

policystring | nullrequired

The policy the DMARC record sets.

one of none, quarantine, reject

policyDomainstring | nullrequired

The domain the DMARC record was found on.

inheritedbooleanrequired

True when the record is the parent domain's, not the domain's own.

verificationCheckedAtstring | nullrequired

When DNS was last checked.

date-time

verificationCurrentbooleanrequired

Whether the domain can send now; see verificationReadinessReason if not.

verificationReadinessReasonstring | nullrequired

Why verificationCurrent is false; null when it is true.

one of inactive_provider, quarantined, provisioning_incomplete, provider_unverified

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

curl https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY"

const response = await fetch('https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
)
data = response.json()["data"]

package main

import (
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "domain": "domain_example",
    "status": "pending",
    "ownershipStatus": "pending",
    "ownershipRecord": {
      "type": "CNAME",
      "name": "Weekend specials",
      "value": "value_example"
    },
    "separateOwnershipRecord": true,
    "provisioningStatus": "awaiting_proof",
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "Weekend specials",
        "value": "value_example"
      }
    ],
    "provider": "provider_example",
    "failureReason": "failureReason_example",
    "readinessChecks": {
      "identity": "pending",
      "dkim": "pending",
      "mailFrom": "pending",
      "dmarc": {
        "status": "valid",
        "policy": "none",
        "policyDomain": "policyDomain_example",
        "inherited": true
      }
    },
    "verificationCheckedAt": "2030-03-14T09:30:00Z",
    "verificationCurrent": true,
    "verificationReadinessReason": "inactive_provider",
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}

Example values are generated from the schema.