Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Get opens and clicks by country

GET/emails/metrics/countries
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Query parameters
start_datestring
end_datestring
domain_idstring<uuid>[]
max items 100
broadcast_idstring<uuid>[]
max items 100
Responses
200

Opens and clicks in the range by the country the reader's address is registered in, most engaged first (BillionSend extension). country is an ISO 3166-1 alpha-2 code, or unknown when the address cannot be placed or the fetch came through a mail provider's image proxy (Gmail, Yahoo, Apple Mail Privacy Protection), whose address is the provider's, not the reader's. Only the country is kept, never the address. People's opens and clicks are counted apart from machines' (bot_opened, bot_clicked). Counts cover whole UTC hours like GET /emails/metrics, and opens and clicks are counted by country from 2026-11-16 on. IP geolocation by DB-IP (db-ip.com), CC BY 4.0. A key held to one domain always reads that domain only.

objectstringrequired
Allowed:list
start_datestringrequired
end_datestringrequired
has_morebooleanrequired
dataobject[]required
Show properties
Array of object
countrystringrequired

ISO 3166-1 alpha-2 code, or unknown

openedintegerrequired

Opens by people

unique_openedintegerrequired

Emails whose first open came from here

bot_openedintegerrequired

Pixel fetches by machines (scanners, prefetches)

clickedintegerrequired

Clicks by people

unique_clickedintegerrequired

Emails whose first click came from here

bot_clickedintegerrequired

Link fetches by machines

401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Restricted API key: a sending_access key, or a key held to one domain that named another domain in domain_id

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
503

The statistics store is not answering; sending is unaffected. Retry shortly.

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://api.billionsend.com/emails/metrics/countries' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "object": "list",
  "start_date": "string",
  "end_date": "string",
  "has_more": true,
  "data": [
    {
      "country": "string",
      "opened": 0,
      "unique_opened": 0,
      "bot_opened": 0,
      "clicked": 0,
      "unique_clicked": 0,
      "bot_clicked": 0
    }
  ]
}

Was this page helpful?