email-inbox-insights

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

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.

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

Headers

Idempotency-Keystring

Client-supplied key. On operations supporting request deduplication, a retained response is replayed for duplicate requests with the same key within the idempotency window (3 hours by default). This protection requires a workspace, organization, or staff-account scope. User-only and unscoped unauthenticated operations, streams, and operations with a separate replay contract do not use this response replay.

On a supported operation, if idempotency protection is unavailable before execution, the API returns 503 IdempotencyUnavailable (E01033) without executing this attempt. Retry with backoff using the same key and request. An operation that takes effect before its response is retained can still execute again on retry.

Two distinct 409 errors signal misuse:

  • request_in_progress (E01004): The same key is currently being processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.
  • idempotency_key_reuse (E01005): The same key has already completed against a different request body or method. Generate a new key.

Recommended key format is <event-type>/<entity-id> (for example welcome-user/usr_abc123).

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

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

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.
domainstring 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.

Example response

{
  "outcome": "enabled",
  "domain": "mail.acme.com"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.