Analytics
Delivery statistics a few seconds after each event, in the dashboard and through GET /emails/metrics.
Every outcome (delivered, bounced, complained, opened, clicked, unsubscribed) is counted a few seconds after it happens. The dashboard’s Analytics page and GET /emails/metrics read the same numbers.
In the dashboard, Analytics shows delivery, open, click, bounce and complaint rates and an events-by-hour chart. You can filter by time range (7, 15 or 30 days), time zone, brand (sending domain), broadcast and recipient domain.
Statistics are kept per hour for 13 months. A broadcast’s own history is not cut off at 13 months. If the statistics service does not answer, the endpoint returns 503 service_unavailable and sending is not affected. Email lists, exports and one email’s events are not statistics; see Logs.
Ask for numbers
GET /emails/metrics needs a full-access API key. The SDKs call it as emails.metrics().
curl "https://api.billionsend.com/emails/metrics?start_date=2026-11-01&end_date=2026-11-14&granularity=daily&metrics=sent&metrics=delivered&metrics=open_rate&dimensions=period" \
-H "Authorization: Bearer bs_..."
| Parameter | What it does |
|---|---|
start_date, end_date |
The range. Statistics are read in whole UTC hours, and the answer shows the start it used. |
timezone |
An IANA zone name such as Europe/Berlin (a UTC offset such as +05:00 is not accepted). Periods are cut in this zone. |
granularity |
hourly, daily, weekly or monthly: the size of a period when dimensions includes period. A range can span at most 10,000 periods. |
metrics |
Repeat it for each metric you want (see below). |
dimensions |
Repeat it for each breakdown: period, domain, email or broadcast. email and broadcast cannot be combined. |
domain_id, email_id, broadcast_id |
Filters. Repeat each up to 100 times. |
The response has totals for the whole range and, when you ask for dimensions, one row per combination in data.
Metrics
| Metric | Counts |
|---|---|
received |
Recipients accepted for sending. It belongs to no domain, broadcast or email, so an answer filtered or broken down by one leaves it out. |
sent, delivered, delivery_delayed, failed, suppressed |
Recipients, by outcome of the send. |
bounced, bounced_permanent, bounced_transient, bounced_undetermined |
Bounces, and the three classes of bounce. |
complained, unsubscribed |
Spam complaints, and recipients who left through the unsubscribe link. |
opened, clicked |
Every open and click. |
unique_opened, unique_clicked |
Emails opened or clicked at least once. |
delivery_rate |
delivered ÷ sent |
bounce_rate |
bounced ÷ sent |
open_rate, click_rate |
unique_opened or unique_clicked ÷ delivered |
complaint_rate, unsubscribe_rate |
complained or unsubscribed ÷ delivered |
Rates are percentages with one decimal, and 0 when there is nothing to divide by. Opens and clicks made by machines, such as privacy proxies and security scanners, are not counted as opens or clicks.
With the email dimension and no email_id, the answer lists up to 1,000 emails created in the range.
Clicks by link
GET /emails/metrics/links (a BillionSend extension, full-access key) lists the links people clicked in a range, most clicked first:
curl "https://api.billionsend.com/emails/metrics/links?start_date=2026-11-01&end_date=2026-11-14&limit=10" \
-H "Authorization: Bearer bs_..."
{
"object": "list",
"start_date": "2026-11-01T00:00:00.000Z",
"end_date": "2026-11-14T23:59:59.999Z",
"has_more": false,
"data": [
{ "link": "https://shop.example.com/sale", "clicked": 412, "bot_clicked": 37 }
]
}
- A link is counted as its scheme, host and path. The query string and the fragment are left out, so a link personalised for each recipient is one row and no recipient’s details are stored.
clickedcounts people;bot_clickedcounts fetches by machines such as security scanners and link previews.- It takes
start_date,end_date,domain_id,broadcast_id(comma-separated) andlimit(1 to 100, default 20), and covers whole UTC hours likeGET /emails/metrics. Clicks are counted by link from November 16, 2026.
Opens and clicks by country and mail client
GET /emails/metrics/countries lists people’s opens and clicks by the country they came from, and GET /emails/metrics/clients lists opens by the mail client that loaded the images (both BillionSend extensions, full-access key), most engaged first:
curl "https://api.billionsend.com/emails/metrics/countries?start_date=2026-11-16&end_date=2026-11-30" \
-H "Authorization: Bearer bs_..."
{
"object": "list",
"start_date": "2026-11-16T00:00:00.000Z",
"end_date": "2026-11-30T23:59:59.999Z",
"has_more": false,
"data": [
{ "country": "BR", "opened": 1840, "unique_opened": 1203, "bot_opened": 95, "clicked": 311, "unique_clicked": 240, "bot_clicked": 22 },
{ "country": "unknown", "opened": 960, "unique_opened": 702, "bot_opened": 410, "clicked": 12, "unique_clicked": 9, "bot_clicked": 3 }
]
}
countryis the ISO 3166-1 alpha-2 code of the country the reader’s address is registered in. It isunknownwhen the address cannot be placed, and for opens through Gmail’s and Yahoo’s image proxies or Apple Mail Privacy Protection: those come from the provider’s address, not the reader’s.clientis one ofgmail,apple_mail,outlook,yahoo,thunderbird,other(a web browser: webmail and clients that do not name themselves look the same) orunknown(no user agent). Clicks are not counted by client, because a click arrives from the browser the mail client hands the link to.- Only the country and the client are kept for statistics, never the address or the user agent.
unique_openedandunique_clickedcount emails whose first open or click came from that country or client. People and machines are counted apart, as inGET /emails/metrics.- Both take
start_date,end_date,domain_idandbroadcast_id(comma-separated), cover whole UTC hours, and return every row (there are only so many countries and clients). Opens and clicks are counted by country and client from November 16, 2026. - IP geolocation by DB-IP, licensed under CC BY 4.0.
Related
Deliverability Insights scores each email and your account. To react to an outcome as it happens instead of counting it later, use webhooks.