# `bird email inbox-insights placement`

## Usage

```bash
bird email inbox-insights placement <sending-domain> [flags]
```

## Description

Read placement for a verified domain owned by the workspace. Dates are inclusive
UTC days, with at most 30 days between from and to. Rates are percentages, and
section statuses distinguish missing measurements. Provider filters add series
lines without filtering the provider table. This read does not enable monitoring.

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

## Examples

```bash
bird email inbox-insights placement <sending-domain>
```

## Options

| Name                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--compare`                   | Include the prior equal-length period, populating compared\_to and every delta field. Possible values: previous\_period.                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `--from`                      | First UTC day of the period, inclusive, in YYYY-MM-DD: the same window convention as the email statistics endpoints, so figures from the two sources cover the same days. Defaults to 30 days before to. It may be at most 30 days before to, which is also the default, so a request naming neither date is already at the limit. Asking for more answers 422: the page pairs these figures with Bird's own per-provider sending statistics, and those are kept for 30 days, so a longer period could only describe two different spans side by side. |
| `--group-by`                  | Bucket size for the series. Defaults to day. Possible values: day, week, month.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `--include-ip-details`        | Include per-IP placement detail for the domain's sending infrastructure. Off by default; only the sending-infrastructure view needs it.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `--response-schema`           | Print the fields this command returns, then exit                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `--series-providers <value>…` | Providers to break the series down by, named as the provider table names them. Each named provider adds one series line; without this, the series carries the domain-wide line only. The provider table is never filtered by this parameter.                                                                                                                                                                                                                                                                                                           |
| `--to`                        | Last UTC day of the period, inclusive, in YYYY-MM-DD. Defaults to today.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

## Related

| Name                                                                                                  | Description                                                    |
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`bird email inbox-insights authentication`](/docs/cli/reference/email-inbox-insights-authentication) | Get email authentication standing for a sending domain         |
| [`bird email inbox-insights blocklists`](/docs/cli/reference/email-inbox-insights-blocklists)         | Check whether a sending domain's infrastructure is blocklisted |
| [`bird email inbox-insights complaints`](/docs/cli/reference/email-inbox-insights-complaints)         | Get the Google-reported spam rate for a sending domain         |
| [`bird email inbox-insights spam-traps`](/docs/cli/reference/email-inbox-insights-spam-traps)         | Get spam-trap hits for a sending domain                        |

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