Statistics, bounces, and audit

These three endpoints give you complete visibility into what happened with your emails: how many were sent, which ones bounced, and a detailed record of each event. Use them to monitor the health of your deliverability, debug delivery issues, and generate activity reports.

Available operations

GET /v1/mail/stats

Returns aggregated server metrics for the specified period.

GET https://api.mailerdash.com/v1/mail/stats

Query params:

Parameter	Type	Default	Description
hours	integer	24	Lookback time window. Maximum 720 (30 days).
key_id	string	—	Admin only. Filters metrics by a specific API key.

Example:

curl https://api.mailerdash.com/v1/mail/stats?hours=48 \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

---

GET /v1/mail/bounces

Lists bounces processed by the system, from most recent to oldest.

GET https://api.mailerdash.com/v1/mail/bounces

Query params:

Parameter	Type	Default	Description
limit	integer	100	Number of results. Maximum 1000.
offset	integer	0	Pagination cursor.
recipient	string	—	Filters by recipient email address.
status	string	—	Filters by DSN code (e.g. 5.1.1 for unknown user).
key_id	string	—	Admin only. Filters by API key.

Response:

{
  "total": 42,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": 17,
      "recipient": "inexistente@example.com",
      "status": "5.1.1",
      "raw": "User unknown",
      "created_at": "2026-06-21T14:32:00Z"
    }
  ]
}

---

GET /v1/mail/audit

Audit log of sends and account actions, with support for advanced filters and CSV export.

GET https://api.mailerdash.com/v1/mail/audit

Query params:

Parameter	Type	Default	Description
limit	integer	100	Number of results. Maximum 1000.
offset	integer	0	Pagination cursor.
app	string	—	Filters by key ID (app in the audit).
event	string	—	Filters by event type: sent, failed, queued. Accepts CSV for multiple: sent,failed.
from	string	—	ISO 8601 start timestamp for the range (e.g. 2026-06-01T00:00:00Z).
to	string	—	ISO 8601 end timestamp for the range.
search	string	—	Substring search against the recipient or subject.
sort_by	string	ts	Sort field: ts, event, subject.
sort_dir	string	desc	Direction: asc or desc.
format	string	json	json (paginated) or csv (full download, ignores limit/offset).

JSON response:

{
  "total": 1240,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "id": 998,
      "ts": "2026-06-22T09:15:00Z",
      "event": "sent",
      "app": "<key-id>",
      "recipient": "cliente@example.com",
      "subject": "Tu recibo #4567",
      "message_id": "<abc123@api.mailerdash.com>"
    }
  ]
}

Example: stats for the last 48 hours

curl "https://api.mailerdash.com/v1/mail/stats?hours=48" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Example: bounces for a specific recipient

curl "https://api.mailerdash.com/v1/mail/bounces?recipient=usuario@example.com&limit=20" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Example: audit of failed sends in a date range

curl "https://api.mailerdash.com/v1/mail/audit?event=failed&from=2026-06-01T00:00:00Z&to=2026-06-22T23:59:59Z&sort_dir=asc" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY"

Export to CSV with ?format=csv

The format=csv parameter on /v1/mail/audit downloads the full log without pagination limits. It is ideal for importing into Excel, Google Sheets, or processing offline with tools like pandas. The event, from, to, and search filters work the same as in JSON mode.

curl "https://api.mailerdash.com/v1/mail/audit?format=csv&from=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -o audit-junio.csv

Reference

For the complete response schema and error codes, see the transactional API reference.