---
title: "Switch Inbox Insights on or off for a sending domain"
method: PATCH
path: "/v1/email/inbox-insights/domains/{sending_domain}"
tags: ["email-inbox-insights"]
---

# Switch Inbox Insights on or off for a sending domain

`PATCH /v1/email/inbox-insights/domains/{sending_domain}`

## Request

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

Changes the workspace's monitoring preference for one of its verified sending
domains. Enabling enrolls the domain with eDataSource before saving the preference.
Disabling removes the preference without removing vendor enrollment or history.
Report reads remain available for verified owned domains regardless of this setting.

A domain switched on for the first time has to be measured before it has
anything to report, so its results start empty and fill in as its mail is
seen. Switching off keeps everything measured so far: switching the domain
back on restores it in full and takes effect immediately, rather than starting
the domain over.

Setting the value it already has changes nothing and answers normally, so this
is safe to repeat.

## Path parameters

- `sending_domain` string, required

## Headers

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

## Request body

- EmailInboxInsightsDomainUpdate: The Inbox Insights setting to change for a sending domain.
  - `monitored` boolean, required: Whether the workspace wants this domain monitored. Enabling enrolls it with eDataSource; disabling removes only the workspace preference and preserves vendor enrollment and measurement history. Verified ownership governs report access.

## Response `200`

The domain's Inbox Insights setting after the change.

- EmailInboxInsightsDomain: One of the workspace's verified sending domains, and whether Inbox Insights is switched on for it.
  - `domain` string, required: The sending domain, lowercased, as it appears in your sending domains.
  - `monitored` boolean, required: Whether Inbox Insights reports on this domain. Switching it off stops the reporting and keeps the measurement history, so switching it back on restores the full history rather than starting again.

## 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)