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
| Name | Default |
|---|---|
email | none |
org_id | none |
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
| Status | Code |
|---|---|
| 400 | invalid_field |
| 400 | missing_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)