Sending domains

Add a sending domain

POST/v1/sending-domains

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

Registers a domain to send from and returns the DNS records to publish. The domain cannot send until those records are in place and verification has succeeded.

Request body

domainstringrequired: 3–253 characters

Returns

Returns 201 Created 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 -X POST https://api.kirora.io/v1/sending-domains \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "domain_example"
  }'

const response = await fetch('https://api.kirora.io/v1/sending-domains', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "domain": "domain_example"
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/sending-domains",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "domain": "domain_example",
    },
)
data = response.json()["data"]

package main

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

func main() {
	body := []byte(`{
	  "domain": "domain_example"
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/sending-domains", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	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 · 201

{
  "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.