Overview
A tenant in TenantCore represents a Microsoft 365 tenant that has been connected to your account via admin consent. Each tenant is owned by the user who performed the consent flow. You can only access tenants you connected.
The correct structure for cold email infrastructure is 12 domains per tenant, 3 mailboxes per domain. Tenants are the top-level container for this structure.
List tenants
Returns all tenants connected to your account, ordered by connection date (most recent first).
Headers
Authorization: Bearer {your_api_key}
curl https://api.tenantcore.io/v1/tenants \
-H "Authorization: Bearer tc_live_your_key"
{
"tenants": [
{
"id": "uuid",
"tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenant_name": "Acme Corp",
"tenant_domain": "acmecorp.onmicrosoft.com",
"default_domain": "acmecorp.onmicrosoft.com",
"domain_count": 12,
"mailbox_count": 36,
"status": null,
"discovery_completed": true,
"exchange_bootstrap_status": "ready",
"consented_at": "2025-01-15T14:32:00Z",
"last_sync_at": "2025-04-20T08:00:00Z"
}
],
"count": 1
}
| Field | Type | Description |
|---|
tenant_id | string | Microsoft tenant GUID |
tenant_name | string | Display name pulled from Microsoft |
tenant_domain | string | The .onmicrosoft.com domain |
default_domain | string | The primary verified custom domain, if set |
domain_count | number | Total custom domains on this tenant |
mailbox_count | number | Total mailboxes across all domains |
discovery_completed | boolean | Whether the initial discovery sync has completed |
exchange_bootstrap_status | string | ready, pending, failed — whether Exchange automation is set up |
consented_at | timestamp | When admin consent was given |
last_sync_at | timestamp | Last successful discovery sync |
Get tenant
Returns a single tenant by its Microsoft tenant GUID.
GET /v1/tenants/{tenant_id}
| Parameter | Type | Description |
|---|
tenant_id | string | The Microsoft tenant GUID (not the TenantCore row ID) |
curl https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-H "Authorization: Bearer tc_live_your_key"
{
"id": "uuid",
"tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenant_name": "Acme Corp",
"tenant_domain": "acmecorp.onmicrosoft.com",
"default_domain": "mail.acmecorp.com",
"domain_count": 8,
"mailbox_count": 24,
"status": null,
"discovery_completed": true,
"exchange_bootstrap_status": "ready",
"smtp_auth_org_enabled": true,
"consented_at": "2025-01-15T14:32:00Z",
"last_sync_at": "2025-04-20T08:00:00Z",
"connected_by": "you@example.com"
}
| Status | Code | Description |
|---|
404 | tenant_not_found | Tenant does not exist or belongs to a different account |
Delete tenant
Removes a tenant and all associated records (domains, mailboxes, sync logs, enforcement events) from your TenantCore account. The Microsoft 365 tenant itself is not affected — only your local records are deleted.
DELETE /v1/tenants/{tenant_id}
This operation is irreversible. All domains, mailboxes, and sync history for this tenant will be permanently removed from TenantCore. The Microsoft tenant and its mailboxes are not modified.
| Parameter | Type | Description |
|---|
tenant_id | string | The Microsoft tenant GUID |
curl -X DELETE \
https://api.tenantcore.io/v1/tenants/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
-H "Authorization: Bearer tc_live_your_key"
{
"status": "deleted",
"tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenant_name": "Acme Corp",
"message": "Tenant and all associated records removed. The Microsoft tenant itself was not affected."
}
| Status | Code | Description |
|---|
404 | tenant_not_found | Tenant does not exist or belongs to a different account |
Connecting new tenants
New tenants cannot be connected via the API — this requires a human admin consent flow. Use the TenantCore app at app.tenantcore.io to connect tenants. Once connected, they are immediately available via the API.
