Domains

Overview

A domain is a custom sending domain added to a Microsoft 365 tenant already connected to TenantCore. TenantCore supports up to 12 domains per connected tenant. TenantCore exposes the Microsoft 365 DNS records required for the domain and tracks authentication state. For supported connected DNS providers, Complete API users can also start TenantCore’s Automatic DNS workflow instead of publishing those records manually. The standard TenantCore structure is:

1 tenant
└── 12 domains
    └── 3 mailboxes each = 36 mailboxes total

Getting a domain ready to send is a two-step DNS process, not one. Add the domain, publish the mail records, verify — Microsoft only generates the DKIM selector CNAMEs after verification succeeds. You publish those separately, then enable DKIM. See Verify domain and Enable DKIM below.

If the domain uses a supported connected DNS provider, the Complete API can start this sequence through the UUID-first Automatic DNS API. Automatic DNS only operates on a domain_id that already belongs to the authenticated TenantCore account.

List domains

Returns all custom domains registered on a tenant, including their last-checked DNS status.

GET /v1/tenants/{tenant_id}/domains

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Example request

curl https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "domains": [
    {
      "id": "uuid",
      "domain_name": "mail.acmecorp.com",
      "is_default": true,
      "is_verified": true,
      "spf_status": "\"v=spf1 include:spf.protection.outlook.com -all\"",
      "dkim_status": "selector1: CNAME -> selector1-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com. | selector1: TXT -> \"v=DKIM1; k=rsa; p=...\"",
      "dmarc_status": "\"v=DMARC1; p=quarantine; rua=mailto:dmarc@acmecorp.com\"",
      "mx_status": "0 mail-acmecorp-com.mail.protection.outlook.com.",
      "last_checked": "2025-04-20T08:00:00Z"
    }
  ],
  "count": 1
}

Response fields

Field	Type	Description
`domain_name`	string	The custom domain
`is_default`	boolean	Whether this is the tenant’s primary domain
`is_verified`	boolean	Whether Microsoft has verified this domain
`spf_status`	string	The raw SPF TXT record currently resolving in public DNS, or an empty/missing indicator
`dkim_status`	string	The raw selector CNAME and key state currently resolving in public DNS. This is a free-form description, not an enum — see Verify domain for how to interpret it
`dmarc_status`	string	The raw DMARC TXT record currently resolving. Microsoft does not provision this — it reflects your own published record
`mx_status`	string	The raw MX record currently resolving
`last_checked`	timestamp	When DNS was last resolved for this domain
`mailbox_count`	number	Mailboxes created on this domain

These four *_status fields are the live, resolved values from public DNS — not a fixed set of states. Match on their content (does it contain the expected Microsoft target?) rather than exact string equality, since the underlying value changes as DNS providers format records differently. Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account

Get domain by TenantCore UUID

Returns the stored operational state for one domain using the TenantCore domain_id. This is a cheap database-backed read; it does not perform a live DNS/provider check.

GET /v1/domains/{domain_id}

Example response:

{
  "id": "DOMAIN_UUID",
  "tenant_resource_id": "TENANT_RESOURCE_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "tenant_name": "Acme Corp",
  "domain_name": "mail.acmecorp.com",
  "is_default": false,
  "is_verified": true,
  "mailbox_count": 3,
  "dns": {
    "mx": "0 mail-acmecorp-com.mail.protection.outlook.com.",
    "spf": "v=spf1 include:spf.protection.outlook.com -all",
    "dmarc": "v=DMARC1; p=quarantine",
    "dkim": "selector records present",
    "dkim_enabled": true,
    "last_checked": "2026-09-27T20:30:00Z"
  },
  "readiness": {
    "microsoft_verified": true,
    "dns_snapshot_available": true,
    "dkim_enabled": true
  }
}

Use this endpoint for ordinary orchestration. Use GET /v1/domains/{domain_id}/dns/plan only when you intentionally need a fresh live DNS plan; that route performs external work and uses the expensive-operation rate-limit bucket. A guessed domain_id belonging to another TenantCore account returns the same 404 domain_not_found response as a nonexistent UUID.

Add domain

Adds a custom domain to a tenant in Microsoft 365 and returns the DNS records you need to publish at your registrar. The domain is created in Microsoft but remains unverified until you publish the verification record and call verify.

POST /v1/tenants/{tenant_id}/domains

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Request body

{
  "domain": "mail.acmecorp.com"
}

Field	Type	Required	Description
`domain`	string	Yes	The custom domain to add. Must be a valid domain. `.onmicrosoft.com` domains are not allowed

Example request

curl -X POST \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.acmecorp.com"}'

Example response

{
  "status": "success",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "domain_id": "DOMAIN_UUID",
  "domain": {
    "id": "DOMAIN_UUID",
    "domain_name": "mail.acmecorp.com",
    "is_default": false,
    "is_verified": false
  },
  "verification_dns_records": [
    {
      "recordType": "domainDnsTxtRecord",
      "label": "@",
      "text": "MS=ms12345678",
      "ttl": 3600
    }
  ],
  "service_configuration_records": [
    {
      "recordType": "domainDnsMxRecord",
      "label": "@",
      "mailExchange": "mail-acmecorp-com.mail.protection.outlook.com",
      "preference": 0,
      "ttl": 3600
    }
  ],
  "live_dns_status": {
    "spf_status": "",
    "dkim_status": "Microsoft did not return DKIM selector records yet.",
    "dmarc_status": "",
    "mx_status": ""
  },
  "dkim_verification_state": {
    "status": "missing",
    "message": "Microsoft has not generated DKIM selectors yet — verify the domain first."
  }
}

DKIM selector CNAMEs are not in service_configuration_records at this point — Microsoft does not generate them until after verification. dkim_verification_state and the empty dkim_status above reflect that; this is expected on every freshly added domain, not an error. domain_id is the TenantCore resource UUID to use immediately with Automatic DNS setup and mailbox creation. You do not need to list domains again just to discover the new resource ID. After adding a domain

Publish the verification_dns_records TXT record at your registrar
Publish the mail records from service_configuration_records (MX, SPF TXT, autodiscover CNAME)
Wait for DNS propagation — usually under 30 minutes, occasionally longer
Call verify

Errors

Status	Code	Description
`400`	`domain_limit_reached`	Tenant already has 12 domains
`400`	—	Invalid domain format, or a `.onmicrosoft.com` domain was supplied
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account

Verify domain

Checks whether the verification TXT record is publicly visible, and if so, verifies the domain with Microsoft and attempts to enable DKIM as part of the same call.

POST /v1/tenants/{tenant_id}/domains/{domain_name}/verify

This is the only endpoint that advances a domain’s stored verification state — List domains and Get DNS records only read what was last recorded here. Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID
`domain_name`	string	The custom domain name

Example request

curl -X POST \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains/mail.acmecorp.com/verify \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key"

Example response — verified

{
  "status": "success",
  "domain": {
    "id": "...",
    "isVerified": true,
    "isDefault": false
  },
  "exchange_organization": "acmecorp.onmicrosoft.com",
  "dkim_enable_result": {
    "status": "success"
  },
  "service_configuration_records": [
    {
      "recordType": "domainDnsCnameRecord",
      "label": "selector1._domainkey",
      "canonicalName": "selector1-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com",
      "ttl": 3600
    },
    {
      "recordType": "domainDnsCnameRecord",
      "label": "selector2._domainkey",
      "canonicalName": "selector2-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com",
      "ttl": 3600
    }
  ],
  "live_dns_status": { "spf_status": "...", "dkim_status": "...", "dmarc_status": "...", "mx_status": "..." },
  "dns_verification_state": { "matched": true },
  "dkim_verification_state": { "status": "missing", "message": "..." },
  "dkim_status": "..."
}

dkim_enable_result here is only an attempt — it commonly fails at this point with Exchange not yet able to see the selector CNAMEs, because you have not published them yet. A verified domain with dkim_enable_result.status other than "success" is normal: the selector CNAMEs are now available in service_configuration_records above. Publish them, then call Enable DKIM directly. Example response — DNS not propagated yet

{
  "detail": {
    "message": "The Microsoft verification TXT record is not visible in public DNS yet. Publish the MS= record and retry.",
    "code": "dns_not_propagated",
    "expected_ms_tokens": ["ms12345678"],
    "visible_ms_tokens": []
  }
}

This is a 409 and is the expected result if you call verify before the TXT record has propagated — not a failure to handle specially, just retry after publishing. Errors

Status	Code	Description
`409`	`dns_not_propagated`	Verification TXT not visible yet — publish it and retry
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account
`500`	—	Unexpected error — see the message for detail

Enable DKIM

Enables DKIM signing for a domain, or returns the selector CNAMEs to publish if Exchange cannot see them yet. This is the same endpoint for both the initial request and the follow-up check — call it again after publishing the records it returns.

POST /v1/tenants/{tenant_id}/domains/{domain_name}/enable-dkim

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID
`domain_name`	string	The custom domain name

Example request

curl -X POST \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains/mail.acmecorp.com/enable-dkim \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key"

Example response — records not published yet (first call)

{
  "detail": {
    "message": "DKIM selector CNAMEs are not resolvable yet.",
    "code": "dkim_dns_required",
    "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "domain_name": "mail.acmecorp.com",
    "exchange_organization": "acmecorp.onmicrosoft.com",
    "expected_dkim_records": {
      "selector1": { "host": "selector1._domainkey", "target": "selector1-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com" },
      "selector2": { "host": "selector2._domainkey", "target": "selector2-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com" }
    }
  }
}

This is a 409 and is the normal first response on a fresh domain — it is how you get the selector targets to publish, not a failure. Publish both CNAMEs, then call this endpoint again. Example response — enabled

{
  "status": "success",
  "domain_name": "mail.acmecorp.com",
  "exchange_organization": "acmecorp.onmicrosoft.com",
  "bootstrap": { "status": "ready", "skipped": true },
  "dkim_enable_result": { "status": "success" },
  "exchange_dkim_config": { "...": "..." },
  "expected_dkim_records": { "...": "..." }
}

Once this returns "success", Microsoft is signing outbound mail for the domain. Calling this endpoint again afterward is safe and idempotent. Errors

Status	Code	Description
`409`	`dkim_dns_required`	Selector CNAMEs not resolvable yet — publish them from `expected_dkim_records` and retry
`409`	`exchange_bootstrap_required`	Exchange management has not finished propagating for this tenant yet. This can happen for a few minutes after a tenant is first connected — retry shortly
`500`	`dkim_enable_failed`	Exchange returned an error TenantCore could not classify — check the message and `exchange_dkim_config`
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account

Get DNS records

Returns the stored DNS records and last-checked DNS status for a specific domain. This does not perform a live DNS re-check — it returns what was last recorded, most recently by Verify domain.

GET /v1/tenants/{tenant_id}/domains/{domain_name}/dns

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID
`domain_name`	string	The custom domain name, e.g. `mail.acmecorp.com`

Example request

curl https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains/mail.acmecorp.com/dns \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "domain_name": "mail.acmecorp.com",
  "is_default": false,
  "is_verified": true,
  "dns_status": {
    "spf": "\"v=spf1 include:spf.protection.outlook.com -all\"",
    "dkim": "selector1: CNAME -> selector1-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com. | selector1: TXT -> \"v=DKIM1; k=rsa; p=...\"",
    "dmarc": "\"v=DMARC1; p=quarantine\"",
    "mx": "0 mail-acmecorp-com.mail.protection.outlook.com."
  },
  "verification_dns_records": [],
  "service_configuration_records": [
    {
      "recordType": "domainDnsMxRecord",
      "label": "@",
      "mailExchange": "mail-acmecorp-com.mail.protection.outlook.com",
      "preference": 0,
      "ttl": 3600
    },
    {
      "recordType": "domainDnsCnameRecord",
      "label": "selector1._domainkey",
      "canonicalName": "selector1-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com",
      "ttl": 3600
    },
    {
      "recordType": "domainDnsCnameRecord",
      "label": "selector2._domainkey",
      "canonicalName": "selector2-mail-acmecorp-com._domainkey.acmecorp.onmicrosoft.com",
      "ttl": 3600
    }
  ],
  "last_checked": "2025-04-20T08:00:00Z"
}

Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account
`404`	`domain_not_found`	Domain is not registered on this tenant

Delete domain

Permanently removes a custom domain from Microsoft 365 and TenantCore.

DELETE /v1/tenants/{tenant_id}/domains/{domain_name}

This is irreversible. Microsoft is authoritative — the domain is deleted there first, and TenantCore’s local record only after Microsoft confirms.

Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID
`domain_name`	string	The custom domain name

Example request

curl -X DELETE \
  https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/domains/mail.acmecorp.com \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: replace-with-a-unique-request-key"

Example response

{
  "status": "success",
  "domain_name": "mail.acmecorp.com",
  "microsoft_deleted": true,
  "local_deleted": true,
  "already_missing_from_microsoft": false
}

If the domain had already been removed on Microsoft’s side (for example, deleted directly in the admin center), this reconciles TenantCore’s local record instead of erroring: microsoft_deleted is false and already_missing_from_microsoft is true. Errors

Status	Code	Description
`409`	`initial_domain`	Microsoft’s initial tenant domain (the default `.onmicrosoft.com` domain) cannot be removed
`409`	`default_domain`	This domain is currently the Microsoft 365 default. Set a different domain as default first
`409`	`domain_has_dependencies`	Microsoft still has objects (users, mailboxes, groups) referencing this domain. The response includes a `dependencies` array with up to 10 — remove or move those first
`409` or matches Graph	`microsoft_domain_delete_failed`	Microsoft refused the delete for a reason not covered above — check `graph_error` in the response
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account
`500`	`domain_delete_failed`	An unexpected error occurred while removing the domain

Overview

Authentication & Errors

Infrastructure

Sending Tool Integrations

Overview

List domains

Get domain by TenantCore UUID

Add domain

Verify domain

Enable DKIM

Get DNS records

Delete domain

​Overview

​List domains

​Get domain by TenantCore UUID

​Add domain

​Verify domain

​Enable DKIM

​Get DNS records

​Delete domain

Overview

List domains

Get domain by TenantCore UUID

Add domain

Verify domain

Enable DKIM

Get DNS records

Delete domain