> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Email Client Breakdown

> See which mail clients and devices open your emails.

Returns the mail clients (Apple Mail, Gmail, Outlook and others) and device types that opened your emails, as shares of unique opens. Use it to decide which clients to test your designs in.

Each email send counts once, attributed to the client of its first open, so a subscriber who reopens an email on another device is not counted twice. Test sends are excluded, and detected email-security scanners are excluded unless you set `includeMachineEngagement=true`. For one campaign, use [Get Campaign Email Client Breakdown](/api-reference/analytics/campaign-email-clients).

## Query Parameters

<ParamField query="period" type="string" default="90d">
  Sliding window over open times. One of: `1h`, `24h`, `7d`, `30d`, `90d`.
  Ignored when `start` and `end` are provided.
</ParamField>

<ParamField query="start" type="string">
  Start of custom time range (ISO 8601). Must be used with `end`.
</ParamField>

<ParamField query="end" type="string">
  End of custom time range (ISO 8601). Must be used with `start`. Max range: 90
  days.
</ParamField>

<ParamField query="emailType" type="string">
  Optional structural filter: `campaign`, `sequence`, or `transactional`.
  Marketer-role personal keys only see campaign and sequence email and receive
  `403` for `transactional`.
</ParamField>

<ParamField query="mailboxProvider" type="string">
  Optional recipient mailbox provider filter, for example `gmail`, `microsoft`,
  `yahoo`, or `icloud`.
</ParamField>

<ParamField query="includeMachineEngagement" type="boolean" default="false">
  Set to `true` to include detected scanner, preview, and tracked asset opens.
</ParamField>

## Response Fields

<ResponseField name="period" type="string">
  Applied period, or `custom` when `start` and `end` were provided.
</ResponseField>

<ResponseField name="totalOpens" type="number">
  Unique opens the breakdown covers. `0` when nothing was opened, in which case
  `clients` and `devices` are empty arrays.
</ResponseField>

<ResponseField name="privacyProxyOpens" type="number">
  Opens that came through the Gmail or Yahoo image proxies or Apple Mail Privacy
  Protection. These report the client but not the reader's device, so they are
  counted under the `unknown` device.
</ResponseField>

<ResponseField name="clients" type="array">
  Mail clients, most opens first. Each item has `key`, `label`, `opens`, and
  `share` (percentage of `totalOpens`, not rounded). `key` is one of
  `apple_mail`, `gmail`, `outlook`, `yahoo_mail`, `thunderbird`,
  `android_mail_app`, `web_browser`, or `other`. `android_mail_app` covers
  Android apps that show mail in a WebView, such as Samsung Email. `web_browser`
  covers webmail, the new Outlook for Windows, and opens recorded from a link
  click without a tracked open. Some apps built on Apple's WebKit, such as
  Outlook for Mac, are reported as `apple_mail`. `other` covers unrecognized and
  missing user agents.
</ResponseField>

<ResponseField name="devices" type="array">
  Device types, most opens first, with the same item fields. `key` is one of
  `desktop`, `mobile`, `tablet`, or `unknown`.
</ResponseField>

`emailType`, `mailboxProvider`, `start`, and `end` are echoed back when you
provide them.

Recipients who never open, or whose client blocks images, are not represented,
so read the shares as "of the people who opened".

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/metrics/clients?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Responses

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "period": "30d",
    "totalOpens": 200,
    "privacyProxyOpens": 150,
    "clients": [
      { "key": "gmail", "label": "Gmail", "opens": 100, "share": 50 },
      { "key": "apple_mail", "label": "Apple Mail", "opens": 80, "share": 40 },
      { "key": "outlook", "label": "Outlook", "opens": 20, "share": 10 }
    ],
    "devices": [
      { "key": "unknown", "label": "Unknown", "opens": 150, "share": 75 },
      { "key": "desktop", "label": "Desktop", "opens": 30, "share": 15 },
      { "key": "mobile", "label": "Mobile", "opens": 20, "share": 10 }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "error": "Invalid emailType. Must be one of: campaign, transactional, sequence"
  }
  ```

  ```json 401 theme={null}
  {
    "success": false,
    "error": "Unauthorized"
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "error": "Personal API keys inherit your workspace role, and the marketer role cannot use this route (it belongs to workspace settings, integrations, or transactional email). Ask the workspace owner for admin access, or use a company API key issued for this workspace."
  }
  ```
</ResponseExample>