Live statistics

If you have questions regarding this API, please visit our API FAQ page.

Returns aggregated sending totals across every sending domain on your account for a rolling window of days, together with the equal-length window immediately before it. The two are designed to be compared directly, so you can render a period-over-period trend without making a second request.

Retrieving live statistics

Make a GET request to https://webapi.inboxroad.com/api/v2/stats/live/ with a valid X-API-Key (see v2 authentication).

curl -X GET 'https://webapi.inboxroad.com/api/v2/stats/live/?range=last_week' \
  -H 'X-API-Key: <your_token>' \
  -H 'Content-Type: application/json'

Returns 200 with a current and a previous object.

Query parameters

Param name	Description
date	Anchor date the window ends on, in YYYY-MM-DD format. Defaults to today (UTC).
range	Length of the window — one of the values listed in How the two windows line up. Default last_week.

How the two windows line up

current ends on date and spans range days. previous covers the same number of days immediately before it. The windows are always adjacent, equal in length, and non-overlapping, which is what makes a percentage change meaningful.

For date=2026-08-07:

range	current	previous
today	Aug 7	Aug 6
yesterday	Aug 6	Aug 5
three_days	Aug 5 – Aug 7	Aug 2 – Aug 4
last_week	Aug 1 – Aug 7	Jul 25 – Jul 31
two_weeks	Jul 25 – Aug 7	Jul 11 – Jul 24
last_month	Jul 9 – Aug 7	Jun 9 – Jul 8

Two things to note:

• These are rolling windows, not calendar ones. last_week anchored on a Friday compares Saturday–Friday against the Saturday–Friday before it — not Monday–Sunday.
• yesterday shifts the whole comparison back a day, so current is yesterday and previous is the day before. today compares today against yesterday.

Caution

If date is today, the current window includes a day that is still accumulating. A last_week comparison is then six complete days plus a partial one, measured against seven complete days, which biases the change downward. Pass an explicit date of yesterday if you need a like-for-like comparison.

Statistics object

Both current and previous contain the same fields.

Field name	Description
total_send	Messages submitted for delivery during the window.
total_delivered	Messages accepted by the receiving server.
total_bounced	Messages that bounced.
bounce_rate	total_bounced / total_send as a percentage, rounded to 1 decimal place.
delivery_rate	100 - bounce_rate, rounded to 1 decimal place.

Counts are 0 — never null — for a window with no sending activity. Both rates are also 0 when nothing was sent, since there is nothing to take a percentage of.

Example response

{
  "current": {
    "total_send": 12043,
    "total_delivered": 11890,
    "total_bounced": 153,
    "bounce_rate": 1.3,
    "delivery_rate": 98.7
  },
  "previous": {
    "total_send": 10877,
    "total_delivered": 10684,
    "total_bounced": 193,
    "bounce_rate": 1.8,
    "delivery_rate": 98.2
  }
}

Possible response codes

Status code	Description
200	Statistics retrieved successfully.
401	Unauthorized.
422	Invalid date format, or range is not one of the allowed values.
429	Rate limit exceeded. See Rate limiting.