Get Email Client Breakdown

GET

api

metrics

clients

curl --request GET \
  --url https://api.sequenzy.com/api/v1/metrics/clients \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sequenzy.com/api/v1/metrics/clients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/metrics/clients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/metrics/clients"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/metrics/clients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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 }
  ]
}

{
  "success": false,
  "error": "Invalid emailType. Must be one of: campaign, transactional, sequence"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "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."
}

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.

Query Parameters

string

default:"90d"

Sliding window over open times. One of: 1h, 24h, 7d, 30d, 90d. Ignored when start and end are provided.

string

Start of custom time range (ISO 8601). Must be used with end.

string

End of custom time range (ISO 8601). Must be used with start. Max range: 90 days.

string

Optional structural filter: campaign, sequence, or transactional. Marketer-role personal keys only see campaign and sequence email and receive 403 for transactional.

string

Optional recipient mailbox provider filter, for example gmail, microsoft, yahoo, or icloud.

boolean

default:"false"

Set to true to include detected scanner, preview, and tracked asset opens.

Response Fields

string

Applied period, or custom when start and end were provided.

number

Unique opens the breakdown covers. 0 when nothing was opened, in which case clients and devices are empty arrays.

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.

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.

array

Device types, most opens first, with the same item fields. key is one of desktop, mobile, tablet, or unknown.

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

curl "https://api.sequenzy.com/api/v1/metrics/clients?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Responses

{
  "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 }
  ]
}

{
  "success": false,
  "error": "Invalid emailType. Must be one of: campaign, transactional, sequence"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "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."
}

Get Email Client Breakdown

curl --request GET \
  --url https://api.sequenzy.com/api/v1/metrics/clients \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.sequenzy.com/api/v1/metrics/clients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sequenzy.com/api/v1/metrics/clients",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sequenzy.com/api/v1/metrics/clients"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sequenzy.com/api/v1/metrics/clients")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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 }
  ]
}

{
  "success": false,
  "error": "Invalid emailType. Must be one of: campaign, transactional, sequence"
}

{
  "success": false,
  "error": "Unauthorized"
}

{
  "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."
}

​Query Parameters

​Response Fields

​Responses

Query Parameters

Response Fields

Responses