---
title: "Switch Inbox Insights on for the workspace's main sending domain"
method: POST
path: "/v1/email/inbox-insights/domain-monitoring"
tags: ["email-inbox-insights"]
---

# Switch Inbox Insights on for the workspace's main sending domain

`POST /v1/email/inbox-insights/domain-monitoring`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/inbox-insights/domain-monitoring`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Switches Inbox Insights on for the workspace's main sending domain, so a
workspace opening the product for the first time has something to read
without having to pick a domain first.

The main sending domain is the one verified domain if there is only one, and
otherwise the verified domain that has sent the most mail over the last 30
days. Where the main domain cannot be identified, nothing is switched on and
the response says so. Which domain matters most is the customer's call, and
not a guess worth making on their behalf.

Safe to repeat. A workspace that already has a domain switched on is left
exactly as it is, and the response says nothing changed.

This chooses a starting point, not a permanent setting: the domain it picks
is switched on the same way as one chosen by hand, and can be switched off
or added to at any time.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

What the call did: a domain switched on, nothing to change, or nothing this endpoint is willing to decide.

- EmailInboxInsightsDomainMonitoringResult: What switching on the workspace's main sending domain did. There are four outcomes, because each one leaves the customer somewhere different: one domain is now reporting, one already was, we could not tell which domain is the main one, or there is no verified domain to report on at all.
  - `outcome` 'enabled' | 'already_on' | 'choice_required' | 'no_verified_domains', required: What switching on the main sending domain did. - `enabled`: Inbox Insights is now switched on for the domain named alongside this. - `already_on`: at least one domain was already switched on, so nothing changed. - `choice_required`: the main sending domain could not be identified, most often because the workspace has several verified domains and no sending to rank them by. Ask the customer to choose. - `no_verified_domains`: the workspace has no verified sending domain, so there is nothing to report on until one is verified.
  - `domain` string, nullable, required: The sending domain this call switched on, lowercased. The server sends a domain with the `enabled` outcome and null with the other three, `already_on` included: that outcome says only that the workspace had already made its choice, not which domain it chose. Read the domain list for that. Check `outcome` first rather than treating a domain as present.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `409`: Resource conflict
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)