Enforcement

Overview

TenantCore periodically checks every mailbox with a provisioned send limit policy against its last 24 hours of send activity, blocking mailboxes that exceed their limit and unblocking ones that have fallen back under it. Every decision is logged. Use the audit log to debug delivery issues or monitor send volume trends. Use the manual trigger to force a check immediately — for example, right after changing a limit — instead of waiting for the next scheduled pass.

Trigger enforcement

Runs an enforcement pass immediately for one tenant, instead of waiting for the scheduled sweep.

POST /v1/tenants/{tenant_id}/enforcement/run

This checks the last 24 hours of send activity for every mailbox with a provisioned limit policy, blocks any mailbox that has exceeded its limit, and unblocks any previously-blocked mailbox that has fallen back under it. Every decision is recorded and appears in List enforcement events immediately after this call returns. This talks to Exchange for every managed mailbox in the tenant and can take longer than a typical request on a tenant with many mailboxes. There is no async job handle — the response is only returned once the pass completes. Path parameters

Parameter	Type	Description
`tenant_id`	string	The Microsoft tenant GUID

Example request

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

Example response — mailboxes checked

{
  "run_id": "8f14e...",
  "status": "success",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "organization": "acmecorp.onmicrosoft.com",
  "mailboxes_checked": 12,
  "blocked": ["sales@mail.acmecorp.com"],
  "unblocked": [],
  "already_blocked": [],
  "errors": [],
  "window_start": "2025-04-19T14:30:00Z",
  "window_end": "2025-04-20T14:30:00Z"
}

Example response — nothing to enforce

{
  "run_id": "8f14e...",
  "status": "skipped",
  "reason": "no provisioned TenantCore mailbox policies",
  "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

A "skipped" status is not an error — it means there was nothing to enforce yet, either because no mailbox has a provisioned limit policy (see Set enforcement) or the tenant has no TenantCore-managed mailboxes at all. A "partial_success" status means enforcement ran but one or more mailboxes hit an error — check the errors array for which ones and why. Errors

Status	Code	Description
`404`	`tenant_not_found`	Tenant does not exist or belongs to a different account
`500`	`enforcement_run_failed`	The pass failed before completing. The response includes the `run_id` used, which you can cross-reference against events already recorded before the failure

List enforcement events

Returns enforcement events across all your tenants, ordered by most recent first. Supports filtering by tenant and action type, and pagination.

GET /v1/enforcement/events

Query parameters

Parameter	Type	Default	Description
`tenant_id`	string	—	Filter events to a specific tenant
`action`	string	—	Filter by action. Only `blocked` or `unblocked` are accepted as filter values — see the note below
`limit`	number	`50`	Number of results to return. Max `200`
`offset`	number	`0`	Pagination offset

Events themselves can carry more action_taken values than the action filter accepts — see Event fields below. already_blocked, checked, block_failed, and unblock_failed all appear in the data but cannot currently be passed as an action filter value; a filter value outside blocked/unblocked is silently ignored and returns unfiltered results.

Example request — all events

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

Example request — blocks only for a specific tenant

curl "https://api.tenantcore.io/v1/enforcement/events?tenant_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&action=blocked" \
  -H "Authorization: Bearer tc_live_your_key"

Example request — paginated

curl "https://api.tenantcore.io/v1/enforcement/events?limit=100&offset=100" \
  -H "Authorization: Bearer tc_live_your_key"

Example response

{
  "events": [
    {
      "id": "uuid",
      "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mailbox_address": "sales@mail.acmecorp.com",
      "action_taken": "blocked",
      "sent_count": 26,
      "limit_value": 25,
      "message": "Mailbox blocked — sent 26 of 25 allowed in last 24h.",
      "created_at": "2025-04-20T14:30:00Z"
    },
    {
      "id": "uuid",
      "tenant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "mailbox_address": "sales@mail.acmecorp.com",
      "action_taken": "unblocked",
      "sent_count": 0,
      "limit_value": 25,
      "message": "Mailbox unblocked — sent 0/25 in last 24h, back under limit.",
      "created_at": "2025-04-21T00:05:00Z"
    }
  ],
  "count": 2,
  "total": 2,
  "limit": 50,
  "offset": 0,
  "filters": {
    "tenant_id": null,
    "action": null
  }
}

Response fields

Field	Type	Description
`events`	array	List of enforcement events
`count`	number	Number of events in this response
`total`	number	Total matching events across all pages
`limit`	number	The limit applied to this request
`offset`	number	The offset applied to this request
`filters`	object	The filters that were applied

Event fields

Field	Type	Description
`tenant_id`	string	The tenant this event belongs to
`mailbox_address`	string	The affected mailbox email address
`action_taken`	string	One of the values below
`sent_count`	number	Send count in the trailing 24-hour window at the time enforcement ran
`limit_value`	number	The configured limit at the time of the event
`message`	string	Human-readable summary of the enforcement action
`created_at`	timestamp	When the enforcement event was logged

action_taken values

Value	Meaning
`blocked`	The mailbox exceeded its limit and was newly added to the Exchange block group
`unblocked`	The mailbox was previously blocked and has fallen back under its limit
`already_blocked`	The mailbox was over its limit but was already in the block group — no change made
`checked`	The mailbox was evaluated and needed no action — within limit and not blocked, or still over limit and remaining blocked
`block_failed`	Enforcement tried to block the mailbox but the Exchange operation failed — see `message`
`unblock_failed`	Enforcement tried to unblock the mailbox but the Exchange operation failed — see `message`

Pagination

Use limit and offset to page through large result sets. The total field in the response tells you how many matching events exist across all pages.

async function getAllEnforcementEvents(apiKey) {
  const limit  = 200;
  let   offset = 0;
  let   all    = [];

  while (true) {
    const res = await fetch(
      `https://api.tenantcore.io/v1/enforcement/events?limit=${limit}&offset=${offset}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const data = await res.json();
    all.push(...data.events);

    if (all.length >= data.total) break;
    offset += limit;
  }

  return all;
}

Errors

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

Overview

Authentication & Errors

Infrastructure

Sending Tool Integrations

Overview

Trigger enforcement

List enforcement events

Event fields

Errors

​Overview

​Trigger enforcement

​List enforcement events

​Event fields

​Pagination

​Errors

Overview

Trigger enforcement

List enforcement events

Event fields

Pagination

Errors