Skip to main content
AhaSend CLI stats commands report email counts and delivery, bounce and delivery-time statistics; this page covers filters and output. Before running the examples, log in with an API key that has the statistics:read:all scope, and replace example.com in --sender-domain with one of your sending domains.

Overview

Available subcommands:
  • deliverability - Message counts and delivery and open rates per period
  • bounces - Bounces per period by classification
  • delivery-time - Average delivery time per period and per recipient domain
  • emails - Email counts of any period, for the whole account or per domain
emails has its own flags. deliverability, bounces and delivery-time take these:
  • --from-time: Start time. The default is 7d, 7 days ago. An empty value leaves the start to the API.
  • --to-time: End time. Without it, the API uses now.
  • --group-by: hour, day (the default), week or month.
  • --sender-domain: Filter by sender domain.
  • --recipient-domain: Filter by recipient domain.
  • --tag: Filter by message tag. A tag cannot hold a comma.
--from-time and --to-time take an RFC 3339 time, such as 2026-09-01T00:00:00Z, or a relative time that counts back from now, such as 24h, 7d or 3mo. --from-time must be before --to-time. With the default --from-time, a --to-time more than 7 days ago fails, so give an earlier --from-time too. An invalid time fails before any request is sent, with exit code 4. --sender-domain, --recipient-domain and --tag can be used multiple times, or take values separated by commas. The CLI sends only the filters you give. For deliverability, bounces and delivery-time, --output json prints the API’s response unchanged. Table and plain output show each period’s time in your local time zone. --output csv writes one row per period, or per classification or recipient domain where the report has them.

Deliverability Statistics

Each period shows how many messages were received, delivered, deferred, bounced, failed, suppressed, opened and clicked. The CLI works out the delivery rate (delivered out of received) and the open rate (opened out of delivered) from these counts.

Export to CSV

Bounce Analysis

Each period shows its bounces by classification, with each classification’s count and its share of the period’s bounces. ahasend stats bounces --help describes the common classifications: The API may return other classifications too; the output shows each as the API names it. See bounce statistics.

Delivery Time Performance

Each period shows the average delivery time, and the time for each recipient domain with the number of delivered messages it covers. Table and plain output give each time in seconds, minutes or hours, whichever reads best. CSV output gives times in seconds, as the API sends them.

Email Counts

stats emails shows the email counts of any period in the account’s history, for the whole account or for each of its domains. Unlike the other stats commands, it is not limited to the account’s message metadata retention period. It needs CLI v0.5.0 or later. Each period shows how many messages were received (accepted by AhaSend, inbound mail included), delivered, bounced and suppressed, how many spam complaints came in, and how many temporary delivery failures (deferred), opens and clicks there were. Deferred, opened and clicked count events, so one message can add more than one; stats deliverability counts messages, so its numbers differ. Opens and clicks are not fully accurate: AhaSend makes a reasonable effort to filter out bots and scanners. The counts cover transactional, campaign and inbound mail, with inbound mail under the domain that received it, and include deleted domains. Sandbox mail is not counted.
stats emails takes --from-time, --to-time, --group-by and --sender-domain, but not --recipient-domain or --tag. Without --from-time, the range starts 30 days before its end, and without --to-time, it ends now. Without --sender-domain, the counts cover every domain the API key can read. Periods are in UTC, and weeks start on Monday. The range includes --from-time and excludes --to-time, and the API rounds it out to whole periods. A range can be at most 31 days with --group-by hour, 366 days with day and week, and 5 years with month. --breakdown domain shows the counts of each domain, and the command fetches every page of domains and shows them as one result. When a page covers another range than the first page, as when the current period ends while the pages are fetched without a --to-time, the command fails with exit code 1 rather than mix ranges: run it again, or give a --to-time in the past. Table and plain output show each period’s time in your local time zone. They show the totals of the whole range, then each row: a period, or with a breakdown, a period of one domain. The rows of a breakdown can add up to a few events more or less than the totals. CSV output has a line per row and no line for the totals; its columns are from_timestamp, to_timestamp, sender_domain, empty without a breakdown, and the counters with the API’s names, such as reception_count. JSON output is the API’s response; with a breakdown, one response with the rows of every page and pagination.has_more false.

Filter by Tag

Command Flags

These flags come from the CLI’s --help. All commands also accept the global flags.

stats bounces

stats deliverability

stats delivery-time

stats emails

Next Steps