GET/v1/reports/messagingbeta

Messaging report

Needs: Read your data (mcp:read)
Plan: Any plan with API access
Limits: 300 a minute per key
Undo: Nothing to undo: this only reads.

Outbound message volume for a period — sent, delivered, read and failed — per day and per WhatsApp number. "Read" depends on customers' read receipts.

A metric this workspace cannot answer is null and listed in unavailable[] with the reason. Never read `null` as zero.

Try it

Query (4)

presetoptionalstring

A named period. Default `last_7_days`. Weeks start on Monday.

fromoptionalstring

First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.

tooptionalstring

Last day (inclusive), YYYY-MM-DD.

timezoneoptionalstring

IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.

This only reads. It uses your real data and changes nothing.

curl -X GET 'https://mcp.wa-api.cloud/v1/reports/messaging?preset=last_month' \
  -H "Authorization: Bearer $API_KEY"

The code reads your key from $API_KEY.

Parameters

Parameters
Field	Type	What it is
preset	string · query	A named period. Default `last_7_days`. Weeks start on Monday.one of: `today`, `yesterday`, `last_7_days`, `last_14_days`, `last_30_days`, `this_month`, `last_month`, `this_week`, `last_week`
from	string · query	First day, YYYY-MM-DD. Give `from` and `to` together; they override `preset`. Up to 186 days.pattern `^\d{4}-\d{2}-\d{2}$`
to	string · query	Last day (inclusive), YYYY-MM-DD.pattern `^\d{4}-\d{2}-\d{2}$`
timezone	string · query	IANA time zone, e.g. `Asia/Dubai`. Default: your workspace time zone.1–64 characters

Headers

Headers
Field	Type	What it is
Authorizationrequired	header	`Bearer $API_KEY` — your API key.
Api-Version	header	The API version to use, e.g. `2026-10-01`. Default: the version your key is pinned to.one of: `2026-10-01` · pattern `^\d{4}-\d{2}-\d{2}$`

Response `200`

The report.

Response fields
Field	Type	What it is
rangerequired	object	The range and timezone these numbers were counted in — always state it when reporting them.
fromrequired	string	First local day (YYYY-MM-DD), inclusive.
torequired	string	Last local day (YYYY-MM-DD), inclusive.
daysrequired	integer	Number of local days in the range.-9007199254740991–9007199254740991
timezonerequired	string	IANA timezone the days were counted in.
started_atrequired	string	Range start as a UTC instant (ISO-8601).
ended_atrequired	string	Range end as a UTC instant (ISO-8601), exclusive.
presetrequired	string or null	The named range used, if any.
totalsrequired	object
sentrequired	integer or null	Outbound, non-bot messages the platform accepted for sending in the range.-9007199254740991–9007199254740991
deliveredrequired	integer or null	Of those, confirmed delivered to the handset.-9007199254740991–9007199254740991
readrequired	integer or null	Of those, marked read. Depends on the customer having read receipts on — a low number is not proof nobody read.-9007199254740991–9007199254740991
failedrequired	integer or null	Rejected or failed (Meta error, invalid number, no open window).-9007199254740991–9007199254740991
delivery_raterequired	number or null	delivered / sent (0-1); null when nothing was sent.
read_raterequired	number or null	read / delivered (0-1); null when nothing was delivered.
failure_raterequired	number or null	failed / sent (0-1); null when nothing was sent.
by_dayrequired	array of object	Per local day. Empty when no daily source is available (see unavailable[]).
daterequired	string	Local calendar day (YYYY-MM-DD) in the reported timezone.
sentrequired	integer or null	-9007199254740991–9007199254740991
deliveredrequired	integer or null	-9007199254740991–9007199254740991
by_channelrequired	array of object	Per WhatsApp number. Empty when the WhatsApp service is not connected or has no numbers.
channel_idrequired	string
namerequired	string or null
typerequired	string or null
sentrequired	integer or null	-9007199254740991–9007199254740991
deliveredrequired	integer or null	-9007199254740991–9007199254740991
template_statsrequired	null	Always null: no service in this stack exposes per-template sends, delivery or read rates.
notesrequired	array of string	How to read these numbers (sources, boundaries, caveats).
unavailablerequired	array of object	Metrics that are UNKNOWN (missing data source), not zero. Say so when reporting; do not fill them in with 0.
metricrequired	string	Which metric or section is missing, e.g. "messages.read".
reasonrequired	string	Why it is missing (not supported by this server version, service not configured, forbidden, temporarily unavailable…).

Errors

Errors are application/problem+json. Branch on code.

Status	Code	When
400	invalid_input	A field is missing or has the wrong format. `errors[]` points at each field. The range is reversed, in the future, longer than 186 days, or the time zone is unknown.
401	unauthenticated	The Authorization header is missing, the key is unknown, expired or revoked.
403	entitlement_required	The workspace's plan does not include API access (`api_access`).
403	insufficient_scope	The key does not have the permission this operation needs.
429	rate_limited	The key or workspace went over its rate limit. Wait for `Retry-After` seconds.
503	upstream_unavailable	A service behind the API is briefly unavailable. Safe to retry with backoff.

Examples

Last month

Response 200

{
  "range": {
    "from": "2026-08-01",
    "to": "2026-08-31",
    "days": 31,
    "timezone": "Asia/Dubai",
    "started_at": "2026-09-16T20:00:00Z",
    "ended_at": "2026-09-23T20:00:00Z",
    "preset": "last_month"
  },
  "totals": {
    "sent": 8120,
    "delivered": 7911,
    "read": 6002,
    "failed": 64,
    "delivery_rate": 0.974,
    "read_rate": 0.759,
    "failure_rate": null
  },
  "by_day": [
    {
      "date": "2026-08-31",
      "sent": 260,
      "delivered": 255
    }
  ],
  "by_channel": [
    {
      "channel_id": "301",
      "name": "Main WhatsApp",
      "sent": 8120,
      "delivered": 7911,
      "type": null
    }
  ],
  "notes": [],
  "unavailable": [],
  "template_stats": null
}

Operation path

The same operation is also at POST /v1/ops/reports_messaging, with every field in the JSON body.