Docs
kirora.ioGet started
Sending domains overviewMenu
On this page

API reference

Sending domains

A sending domain is a domain your email is sent from, with the DNS records that prove you own it. Nothing sends email from an address until its domain is verified here, and a domain can be verified in only one workspace, so use a subdomain for staging.

Endpoints

EndpointRequest
List sending domainsGET /v1/sending-domains
Add a sending domainPOST /v1/sending-domains
Retrieve a sending domainGET /v1/sending-domains/{id}
Delete a sending domainDELETE /v1/sending-domains/{id}
Check a sending domainPOST /v1/sending-domains/{id}/check
Retrieve a sending domain's usageGET /v1/sending-domains/{id}/usage
Ask for a sending domain review againPOST /v1/sending-domains/{id}/review

The SendingDomain object

SendingDomain example
{
  "id": "0192f3f0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "domain": "mail.acme-shop.com",
  "status": "pending",
  "failureReason": null,
  "lastCheckedAt": "2026-10-01T09:45:00.000Z",
  "dnsRecords": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "kirora1._domainkey.mail.acme-shop.com",
      "host": "kirora1._domainkey.mail",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7v3k2x",
      "matches": false,
      "reason": "No TXT record found at kirora1._domainkey.mail.acme-shop.com"
    },
    {
      "purpose": "mailFrom",
      "type": "MX",
      "name": "bounce.mail.acme-shop.com",
      "host": "bounce.mail",
      "value": "10 feedback-smtp.eu-central-1.amazonses.com",
      "matches": false,
      "reason": "No MX record found at bounce.mail.acme-shop.com"
    },
    {
      "purpose": "mailFrom",
      "type": "TXT",
      "name": "bounce.mail.acme-shop.com",
      "host": "bounce.mail",
      "value": "v=spf1 include:amazonses.com ~all",
      "matches": false,
      "reason": "No TXT record found at bounce.mail.acme-shop.com"
    }
  ],
  "checks": {
    "ownership": "pending",
    "dkim": "pending",
    "mailFrom": "pending",
    "dmarc": null,
    "bimi": null
  },
  "review": {
    "status": "not_requested",
    "declineReason": null
  },
  "createdAt": "2026-10-01T09:30:00.000Z",
  "updatedAt": "2026-10-01T09:45:00.000Z"
}
idstringrequired

uuid

domainstringrequired
statusstringrequired

Whether the domain can send: pending until its DNS records are all found; awaiting_review, you own it but a person at Kirora has not cleared it to send yet, and it is set up the moment they do (review says more); verified, it can send; verification_lost, it was verified but a record has since gone missing, and nothing sends from it until the record is back; failed, see failureReason; quarantined, the domain is already set up by another account, so nothing sends from it until Kirora support reviews it.

one of pending, awaiting_review, verified, verification_lost, failed, quarantined

failureReasonstring | nullrequired

Why verification failed, when it has.

lastCheckedAtstring | nullrequired

When DNS was last checked.

date-time

dnsRecordsSendingDomainDnsRecord[]required

The records to publish at your DNS host, the ownership record first.

7 child attributes
purposestringrequired

ownership: proves you control the domain, and holds the key that signs its mail; dkim: another signing key record; mailFrom: the bounce. subdomain that receives bounces and aligns SPF.

one of ownership, dkim, mailFrom

typestringrequired

one of CNAME, TXT, MX

namestringrequired

The full hostname to publish the record at.

hoststringrequired

The name without the registered domain, which most DNS hosts ask for, since they add the domain themselves: sel._domainkey for sel._domainkey.example.com, @ for the domain itself.

valuestringrequired

What the record must contain.

matchesbooleanrequired

Whether the last check found the record as given.

reasonstring | nullrequired

Why it does not match, such as what DNS holds there; null when it does.

checksobjectrequired

Each check's state, for showing progress; status is what decides.

5 child attributes
ownershipstringrequired

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

one of pending, verified

dkimstringrequired

The DKIM signing records.

one of pending, verified, failed

mailFromstringrequired

The bounce. (MAIL FROM) records.

one of pending, verified, failed

dmarcobject | nullrequired

The DMARC record covering the domain, which marketing email needs; null before the first check.

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.

bimiobject | nullrequired

BIMI, for the brand's logo beside its email: guidance, never a requirement. Mailboxes show it only with DMARC at quarantine or reject. Null until a check reads it.

3 child attributes
statusstringrequired

Whether default._bimi.<domain> holds a BIMI record.

one of present, missing, unknown

logoUrlstring | nullrequired

Its logo (l=): an SVG Tiny PS file over HTTPS.

certificateUrlstring | nullrequired

Its mark certificate (a=, a VMC or CMC), which Gmail and Apple Mail need before showing the logo; Yahoo can show it without one.

reviewobjectrequired

Its sending review (SENDING_REVIEW_REQUIRED).

2 child attributes
statusstringrequired

Whether a person at Kirora has cleared the domain to send; until then it has no provider identity (status is awaiting_review once you own it), and nothing sends from it, not even a test. not_requested: proven yours, waiting for the workspace's sending profile (website, what it sends, how contacts agreed), which asks for review once filled in. in_review: waiting for a person, usually within a day. A subdomain of an approved domain is approved when proven.

one of not_requested, in_review, approved, declined

declineReasonstring | nullrequired

Why it was declined; null unless declined.

createdAtstringrequired

date-time

updatedAtstringrequired

date-time