Menu

Unread summary

1 endpoint in the Mattering Comms API. Service tier only.

GET unread/summary/ Service tier

Cross-app unread summary for ONE user in ONE org: the toolbar badge feed.

INTERNAL TIER ONLY (mounted solely under /api/internal/v1/ behind InternalAPIGuard: see MatteringComms/urls.py). Unlike every other handler in this module it takes explicit email + org_id query params: the caller is a trusted sibling service (mattering_platform) asking on behalf of a user it has already session-authenticated. It must NEVER be exposed on the /api/user/v1/ tier, where a bearer caller could read another user's unread state by naming their email.

Identity is by EMAIL, the canonical cross-service key (username==email convention: Known Pitfall: Cross-Service Identity; never a local PK). An unknown email means "no Comms presence yet" and returns zeros, not 404 : the badge simply shows nothing.

Returns {"data": {"total_unread", "mention_unread", "channels"}, "meta": {}} computed by the SAME shared helper as the sidebar badges (unread.unread_counts): org-scoped memberships, notify_level enforced (mute passes only personal @mentions; mentions-level counts @user and @channel/@here), deleted messages and thread replies excluded. Grouped aggregate queries only: bounded regardless of channel count.

URL

  • Service tierhttps://comms.mattering.io/api/internal/v1/unread/summary/

Query parameters

NameDefault
emailnone
org_idnone

Responses

200 data and meta envelope

{
  "data": "...",
  "meta": {}
}

200 data and meta envelope

{
  "data": {
    "total_unread": 0,
    "mention_unread": 0,
    "channels": 0
  },
  "meta": {}
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_field
400missing_field

Example

curl -X GET "https://comms.mattering.io/api/internal/v1/unread/summary/?email=...&org_id=..." \
  -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
  -H "X-Internal-Org-Id: $ORG_ID" \
  -H "X-Internal-User-Email: you@example.com"

Source: CommsCore/api.py (api.unread_summary)

All Comms resources
Start Free Explore our Products