Overview

Mailbox API operations are resource-bound. TenantCore does not accept an arbitrary Microsoft mailbox, domain, or tenant and then operate on it. The authorization chain is:

API key
  → TenantCore account UUID
    → TenantCore tenant/domain/mailbox UUID
      → owned Microsoft resource
        → Microsoft / Exchange operation

For new integrations, use the TenantCore UUIDs returned by the API:

tenant_resource_id — TenantCore tenant-row UUID
domain_id — TenantCore domain-row UUID
mailbox_id — TenantCore mailbox-row UUID

Mailbox passwords, TOTP seeds, and current MFA codes are not revealable through the public API. The mailbox detail endpoint exposes non-sensitive credential/MFA status only.

All mailbox/provider writes require Idempotency-Key. Microsoft/Exchange-heavy mailbox operations use the public API’s expensive-operation rate-limit bucket.

List tenant mailboxes

Returns every mailbox already registered to an owned TenantCore tenant.

GET /v1/tenants/{tenant_id}/mailboxes

Use the TenantCore tenant_resource_id where possible. The existing Microsoft tenant GUID remains accepted only because TenantCore resolves it against the authenticated account before returning data.

curl https://api.tenantcore.io/v1/tenants/TENANT_RESOURCE_UUID/mailboxes \
  -H "Authorization: Bearer tc_live_your_key"

Example response:

{
  "tenant_resource_id": "TENANT_RESOURCE_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "mailboxes": [
    {
      "id": "MAILBOX_UUID",
      "display_name": "Sales Outreach",
      "primary_smtp": "sales@mail.acmecorp.com",
      "user_principal_name": "sales@mail.acmecorp.com",
      "mail_nickname": "sales",
      "account_enabled": true,
      "domain_id": "DOMAIN_UUID",
      "domain_name": "mail.acmecorp.com",
      "tenant_name": "Acme Corp",
      "managed_by_tenantcore": true,
      "password_set_at": "2026-09-27T20:00:00Z",
      "daily_send_limit": 25,
      "sends_today": 12,
      "blocked_at": null,
      "created_at": "2026-09-27T19:45:00Z"
    }
  ],
  "count": 1
}

The response is explicitly allow-listed. Database-only credential/vault fields are never returned.

List domain mailboxes

Returns mailboxes through an owned TenantCore domain UUID.

GET /v1/domains/{domain_id}/mailboxes

curl https://api.tenantcore.io/v1/domains/DOMAIN_UUID/mailboxes \
  -H "Authorization: Bearer tc_live_your_key"

Example response:

{
  "tenant_resource_id": "TENANT_RESOURCE_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "domain_id": "DOMAIN_UUID",
  "domain_name": "mail.acmecorp.com",
  "mailboxes": [],
  "count": 0
}

A guessed domain UUID from another TenantCore account returns the same 404 domain_not_found shape as a nonexistent UUID.

Get one mailbox

Returns one mailbox strictly from its TenantCore mailbox UUID.

GET /v1/mailboxes/{mailbox_id}

curl https://api.tenantcore.io/v1/mailboxes/MAILBOX_UUID \
  -H "Authorization: Bearer tc_live_your_key"

Example response:

{
  "tenant_resource_id": "TENANT_RESOURCE_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "mailbox": {
    "id": "MAILBOX_UUID",
    "display_name": "Sales Outreach",
    "primary_smtp": "sales@mail.acmecorp.com",
    "user_principal_name": "sales@mail.acmecorp.com",
    "mail_nickname": "sales",
    "account_enabled": true,
    "domain_id": "DOMAIN_UUID",
    "domain_name": "mail.acmecorp.com",
    "tenant_name": "Acme Corp",
    "managed_by_tenantcore": true,
    "password_set_at": "2026-09-27T20:00:00Z",
    "daily_send_limit": 25,
    "sends_today": 12,
    "blocked_at": null,
    "created_at": "2026-09-27T19:45:00Z",
    "security": {
      "credential": {
        "managed": true,
        "sync_status": "synced",
        "secret_updated_at": "2026-09-27T20:00:00Z",
        "has_error": false
      },
      "mfa": {
        "status": "managed",
        "seed_secured": true,
        "verified_at": "2026-09-27T20:05:00Z"
      }
    },
    "sending_connection": {
      "id": "CONNECTION_UUID",
      "status": "connected",
      "integration_id": "INTEGRATION_UUID",
      "provider": "instantly",
      "integration_name": "Primary Instantly",
      "provider_account_id": "provider-account-id",
      "provider_account_email": "sales@mail.acmecorp.com",
      "has_error": false,
      "connected_at": "2026-09-27T20:10:00Z",
      "updated_at": "2026-09-27T20:10:00Z"
    }
  }
}

The security object is status-only. It never contains a password, external vault secret ID, TOTP seed, or current MFA code. sending_connection is null when TenantCore has no persisted sending-tool connection for the mailbox. Raw provider errors are never exposed; use has_error plus the integration/retry workflow instead.

Create mailboxes

Creates one or more mailboxes through an existing TenantCore domain UUID.

POST /v1/domains/{domain_id}/mailboxes

The previous contract that accepted a free-form domain string is retired. TenantCore now resolves the domain resource first, proves that its parent tenant belongs to the authenticated account, and only then calls Microsoft.

curl -X POST \
  https://api.tenantcore.io/v1/domains/DOMAIN_UUID/mailboxes \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: mailbox-batch-001" \
  -H "Content-Type: application/json" \
  -d '{
    "account_password": "SecureP@ssw0rd!",
    "mailboxes": [
      {"name":"Sales Outreach","email":"sales@mail.acmecorp.com"},
      {"name":"Lead Gen","email":"leads@mail.acmecorp.com"}
    ]
  }'

Request body:

Field	Type	Required	Description
`account_password`	string	Yes	Initial Microsoft account password. Minimum 8 characters
`mailboxes`	array	Yes	One or more mailboxes. Existing + requested cannot exceed 3 on the selected TenantCore domain
`mailboxes[].name`	string	Yes	Display name
`mailboxes[].email`	string	Yes	Full mailbox address. It must belong to the domain represented by `domain_id`

The domain name is not supplied separately. The path domain_id is the authorization anchor. Example response:

{
  "status": "completed",
  "tenant_resource_id": "TENANT_RESOURCE_UUID",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "domain_id": "DOMAIN_UUID",
  "domain_name": "mail.acmecorp.com",
  "created_count": 2,
  "exists_count": 0,
  "failed_count": 0,
  "credential_synced_count": 2,
  "credential_failed_count": 0,
  "results": [
    {
      "mailbox_id": "MAILBOX_UUID",
      "name": "Sales Outreach",
      "email": "sales@mail.acmecorp.com",
      "status": "created",
      "mailbox": {
        "display_name": "Sales Outreach",
        "primary_smtp": "sales@mail.acmecorp.com",
        "user_principal_name": "sales@mail.acmecorp.com",
        "mail_nickname": "sales"
      },
      "credential_sync_status": "synced"
    }
  ]
}

Raw upstream provider payloads and exception text are sanitized from this public response.

Mailbox creation errors

Status	Code	Meaning
`400`	`invalid_password`	Password is shorter than 8 characters
`400`	`mailboxes_required`	Request contains no mailboxes
`400`	`mailbox_domain_mismatch`	Mailbox address does not belong to the TenantCore domain identified by `domain_id`
`400`	`duplicate_mailbox`	Same address appears twice in the batch
`400`	`mailbox_limit_reached`	Domain would exceed 3 mailboxes
`404`	`domain_not_found`	Domain UUID does not exist or belongs to another account
`409`	`tenant_organization_missing`	TenantCore cannot resolve the Microsoft organization domain needed for Exchange
`502`	`mailbox_batch_failed`	Microsoft could not provision any mailbox in the batch
`502`	`mailbox_provider_operation_failed`	Microsoft/Exchange operation failed

Retired free-form provisioning contract

POST /v1/tenants/{tenant_id}/mailboxes

returns:

410 mailbox_domain_name_contract_retired

Use POST /v1/domains/{domain_id}/mailboxes instead.

Reset mailbox password

Resets the Microsoft password for a TenantCore-created mailbox.

POST /v1/mailboxes/{mailbox_id}/reset-password

curl -X POST \
  https://api.tenantcore.io/v1/mailboxes/MAILBOX_UUID/reset-password \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: mailbox-password-reset-001" \
  -H "Content-Type: application/json" \
  -d '{"new_password":"NewSecureP@ssw0rd!"}'

The password is never echoed in the response. TenantCore resets it in Microsoft and synchronizes the new value into the configured credential vault.

{
  "status": "success",
  "mailbox_id": "MAILBOX_UUID",
  "mailbox": "sales@mail.acmecorp.com",
  "password_set_at": "2026-09-27T20:30:00Z",
  "credential_sync_status": "synced"
}

The previous password stops working after Microsoft accepts the reset. Any external system still using the old credential must be updated.

Common errors:

Status	Code	Meaning
`400`	`invalid_password`	New password is shorter than 8 characters
`404`	`mailbox_not_found`	UUID does not exist or is not owned by this TenantCore account
`409`	`mailbox_not_managed_by_tenantcore`	Mailbox was not created by TenantCore
`502`	`mailbox_password_vault_sync_failed`	Microsoft changed the password but secure vault synchronization failed; reset again after vault service is restored

The older tenant-scoped reset route remains available for compatibility, but new integrations should use the mailbox UUID route above.

Get mailbox usage

Returns current stored daily usage and effective mailbox cap information.

GET /v1/mailboxes/{mailbox_id}/usage

curl https://api.tenantcore.io/v1/mailboxes/MAILBOX_UUID/usage \
  -H "Authorization: Bearer tc_live_your_key"

Example:

{
  "mailbox_id": "MAILBOX_UUID",
  "primary_smtp": "sales@mail.acmecorp.com",
  "display_name": "Sales Outreach",
  "account_enabled": true,
  "daily_send_limit": 25,
  "sends_today": 12,
  "remaining_sends": 13,
  "is_blocked": false,
  "blocked_at": null,
  "utilization_pct": 48.0
}

This endpoint does not trigger a fresh Microsoft telemetry collection. It returns TenantCore’s current usage state; the reputation/Reports experience provides broader historical telemetry separately.

Delete mailbox

Permanently removes a TenantCore-created mailbox from Microsoft and TenantCore.

DELETE /v1/mailboxes/{mailbox_id}

curl -X DELETE \
  https://api.tenantcore.io/v1/mailboxes/MAILBOX_UUID \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: delete-mailbox-001"

TenantCore verifies mailbox ownership before Microsoft is contacted and performs the required Microsoft-side and credential cleanup before removing the TenantCore mailbox resource. Example response:

{
  "status": "success",
  "mailbox_id": "MAILBOX_UUID",
  "mailbox": "sales@mail.acmecorp.com",
  "microsoft_deleted": true,
  "local_deleted": true,
  "already_missing_from_microsoft": false,
  "cloud_app_admin_removed": true,
  "cloud_app_admin_was_present": true,
  "credential_cleanup_status": "deleted"
}

Raw Microsoft error bodies are not returned through the public API. Use the response request_id when support needs to trace the underlying operation.

Direct mailbox update remains retired

PATCH /v1/tenants/{tenant_id}/mailboxes/{mailbox_id}

returns:

410 mailbox_direct_update_retired

Display-name editing is not exposed until TenantCore can update Microsoft and TenantCore atomically. Send-limit changes must use the Exchange-enforced policy endpoints below rather than changing a mailbox database field.

Send-limit enforcement

Sending limits are Exchange-enforced policies. Tenant-wide policy needs only an owned tenant. A domain override now requires a TenantCore domain_id, not a free-form domain name.

Set enforcement

POST /v1/tenants/{tenant_id}/mailbox-limits

Tenant-wide:

curl -X POST \
  https://api.tenantcore.io/v1/tenants/TENANT_RESOURCE_UUID/mailbox-limits \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: limit-tenant-001" \
  -H "Content-Type: application/json" \
  -d '{"daily_send_limit":25}'

Domain-scoped:

curl -X POST \
  https://api.tenantcore.io/v1/tenants/TENANT_RESOURCE_UUID/mailbox-limits \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: limit-domain-001" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_send_limit":25,
    "domain_id":"DOMAIN_UUID"
  }'

Example response:

{
  "status": "success",
  "tenant_id": "MICROSOFT_TENANT_GUID",
  "daily_send_limit": 25,
  "domain_id": "DOMAIN_UUID",
  "domain_name": "mail.acmecorp.com",
  "scope_label": "mail.acmecorp.com",
  "policy": {},
  "provisioning": {}
}

A supplied domain_id must belong to the same authenticated TenantCore tenant. A domain from another TenantCore account or another owned tenant cannot be used as the scope. The old domain_scope: "mail.acmecorp.com" request field returns 410 domain_name_scope_retired so an old request cannot silently become tenant-wide enforcement.

Get enforcement policy

Tenant-wide:

GET /v1/tenants/{tenant_id}/mailbox-limits

Domain-scoped:

GET /v1/tenants/{tenant_id}/mailbox-limits?domain_id=DOMAIN_UUID

The response contains both domain_id and readable domain_name. When no policy exists, daily_send_limit is null; that is a normal 200 response.

List enforcement scopes

GET /v1/tenants/{tenant_id}/mailbox-limits/scopes

Each domain-scoped row includes the TenantCore domain_id as well as the readable domain name.

List effective mailbox policies

GET /v1/tenants/{tenant_id}/mailbox-limits/mailboxes

Each mailbox policy row is augmented with its TenantCore mailbox_id, so subsequent API actions do not need to use an email address as the resource identifier.

Remove enforcement

Tenant-wide:

DELETE /v1/tenants/{tenant_id}/mailbox-limits

Domain-scoped:

DELETE /v1/tenants/{tenant_id}/mailbox-limits?domain_id=DOMAIN_UUID

curl -X DELETE \
  "https://api.tenantcore.io/v1/tenants/TENANT_RESOURCE_UUID/mailbox-limits?domain_id=DOMAIN_UUID" \
  -H "Authorization: Bearer tc_live_your_key" \
  -H "Idempotency-Key: remove-limit-domain-001"

Exchange cleanup runs before the policy is removed locally. If no policy exists, TenantCore returns a normal not_found result rather than treating that state as an API failure.

Public API security boundary

The mailbox API intentionally does not expose:

arbitrary Microsoft tenant or mailbox lookup
mailbox password reveal
external vault record IDs
TOTP seed reveal
current MFA-code generation
raw Microsoft/Exchange responses
generic Microsoft command passthrough
arbitrary provider calls

Those boundaries keep TenantCore as the source of truth and ensure API automation can only act on resources already associated with the authenticated TenantCore account.

Overview

Authentication & Errors

Infrastructure

Sending Tool Integrations

Mailboxes

Overview

List tenant mailboxes

List domain mailboxes

Get one mailbox

Create mailboxes

Mailbox creation errors

Retired free-form provisioning contract

Reset mailbox password

Get mailbox usage

Delete mailbox

Direct mailbox update remains retired

Send-limit enforcement

Set enforcement

Get enforcement policy

List enforcement scopes

List effective mailbox policies

Remove enforcement

Public API security boundary

​Overview

​List tenant mailboxes

​List domain mailboxes

​Get one mailbox

​Create mailboxes

​Mailbox creation errors

​Retired free-form provisioning contract

​Reset mailbox password

​Get mailbox usage

​Delete mailbox

​Direct mailbox update remains retired

​Send-limit enforcement

​Set enforcement

​Get enforcement policy

​List enforcement scopes

​List effective mailbox policies

​Remove enforcement

​Public API security boundary

Overview

List tenant mailboxes

List domain mailboxes

Get one mailbox

Create mailboxes

Mailbox creation errors

Retired free-form provisioning contract

Reset mailbox password

Get mailbox usage

Delete mailbox

Direct mailbox update remains retired

Send-limit enforcement

Set enforcement

Get enforcement policy

List enforcement scopes

List effective mailbox policies

Remove enforcement

Public API security boundary