Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

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.
  • clicked counts people; bot_clicked counts fetches by machines such as security scanners and link previews.
  • It takes start_date, end_date, domain_id, broadcast_id (comma-separated) and limit (1 to 100, default 20), and covers whole UTC hours like GET /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 }
  ]
}
  • country is the ISO 3166-1 alpha-2 code of the country the reader’s address is registered in. It is unknown when 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.
  • client is one of gmail, apple_mail, outlook, yahoo, thunderbird, other (a web browser: webmail and clients that do not name themselves look the same) or unknown (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_opened and unique_clicked count emails whose first open or click came from that country or client. People and machines are counted apart, as in GET /emails/metrics.
  • Both take start_date, end_date, domain_id and broadcast_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.

Deliverability Insights scores each email and your account. To react to an outcome as it happens instead of counting it later, use webhooks.

Was this page helpful?