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

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

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.

API-key and service-account calls require Insights preview access for your organization.

## Code samples

### TypeScript

```ts
// Requires Insights preview access for the organization.
const result = await bird.email.inboxInsights.domainMonitoring.upsert();
console.log(result.outcome, result.domain);
```

### Python

```py
# Requires Insights preview access for the organization.
result = client.email.inbox_insights.domain_monitoring.upsert()
print(result.outcome, result.domain)
```

### Go

```go
// Requires Insights preview access for the organization.
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
	log.Fatal(err)
}
ctx := context.Background()
report, err := client.Email.InboxInsights.DomainMonitoring.Upsert(ctx)
if err != nil {
	log.Fatal(err)
}
encoded, err := json.MarshalIndent(report, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Println(string(encoded))
```

### PHP

```php
// Requires Insights preview access for the organization.
$result = $bird->email->inboxInsights->domainMonitoring->upsert();
var_dump($result->getOutcome(), $result->getDomain());
```

### CLI

```sh
bird email inbox-insights domain-monitoring upsert
```

### cURL

```sh
curl -X POST "https://us1.platform.bird.com/v1/email/inbox-insights/domain-monitoring" \
  -H "Authorization: Bearer $TOKEN"
```

## Example response `200`

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

## Response body

- `outcome` (string, 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.

  Possible values: `enabled`, `already_on`, `choice_required`, `no_verified_domains`
- `domain` (nullable string, 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.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)