Ask for a sending domain review againMenu

Ask for a sending domain review again

POST/v1/sending-domains/{id}/review

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

Works with integration, agent and partner keys.

Safe to retry: a repeat sets the same values again. About idempotency

A person at Kirora reviews each sending domain before it can send, against the workspace's sending profile (website, mailKind, contactOptIn in workspace settings); it is asked for on its own once the domain is proven yours and the profile is filled in. Call this to ask again after a decline, once you have changed what its review.declineReason names. Refused with CONFLICT when the domain is already approved or not yet proven yours, and VALIDATION_ERROR while the sending profile is incomplete.

Path parameters

idstringrequired

The sending domain's id.

uuid

Header parameters

Kirora-Workspacestringoptional

Partner keys only: the child workspace to act in, by the external id the partner gave it. Without it, a partner key acts in its own workspace. Any other key that sends it is refused with 403, and an unknown workspace is 404.

pattern ^[A-Za-z0-9._:-]{1,128}$

Idempotency-Keystringoptional

Makes a retry safe: a repeat with the same key and body within 24 hours gets the first response again, with Idempotency-Replay: true. The same key with another request is 409 IDEMPOTENCY_KEY_REUSED; while the first is still running, 409 IDEMPOTENCY_KEY_IN_USE; after an unsafe first request failed or never returned, 409 IDEMPOTENCY_KEY_OUTCOME_UNKNOWN. Use a new key, such as a UUID, for each new request.

8–255 characters

Returns

Returns 200 OK with a SendingDomain in data. It can also return 409 Conflict; see the statuses below. Otherwise returns an error; Errors lists every code and which to retry.

200 OKThe domain, its review now in_review.
409 ConflictThe request conflicts with current state — a duplicate unique value, or a resource whose status does not allow this operation.

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

Headers on `200 OK`

Idempotency-Replaystringoptional

true when this is the stored response to an earlier request with the same key.

one of true

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

const response = await fetch('https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/review', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`Kirora API ${response.status}: ${await response.text()}`);
const { data } = await response.json();

import os

import requests

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

package main

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

func main() {
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/review", 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()
	if res.StatusCode >= 300 {
		msg, _ := io.ReadAll(res.Body)
		panic(fmt.Sprintf("Kirora API %d: %s", res.StatusCode, msg))
	}

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

using System.Net.Http.Headers;
using System.Text.Json;

using var http = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.kirora.io/v1/sending-domains/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/review");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("KIRORA_API_KEY"));

using var response = await http.SendAsync(request);
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"Kirora API {(int)response.StatusCode}: {await response.Content.ReadAsStringAsync()}");

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var data = document.RootElement.GetProperty("data");

Response · 200

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "domain": "domain_example",
    "status": "pending",
    "failureReason": "failureReason_example",
    "lastCheckedAt": "2030-03-14T09:30:00Z",
    "dnsRecords": [
      {
        "purpose": "ownership",
        "type": "CNAME",
        "name": "name_example",
        "host": "host_example",
        "value": "value_example",
        "matches": true,
        "reason": "reason_example"
      }
    ],
    "checks": {
      "ownership": "pending",
      "dkim": "pending",
      "mailFrom": "pending",
      "dmarc": {
        "status": "valid",
        "policy": "none",
        "policyDomain": "policyDomain_example",
        "inherited": true
      },
      "bimi": {
        "status": "present",
        "logoUrl": "logoUrl_example",
        "certificateUrl": "certificateUrl_example"
      }
    },
    "review": {
      "status": "not_requested",
      "declineReason": "declineReason_example"
    },
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}

Ask for a sending domain review again

Path parameters

Header parameters

Returns

Headers on 200 OK

Headers on `200 OK`