GET /sms/unread

Unread counts

Scope	messages:read
Role permission	Phone numbers — only lines the credential is authorized for
Cost	Free

How many messages you have not read, per line and in total. Both are returned so a client rendering one badge does not have to add them up and cannot disagree with the per-line numbers.

An API key has no user behind it and therefore no personal unread state; it gets the line-level counts, which is the only honest answer available to a credential that is not a person.

Query parameters

Name	Type	Required	Example	Description
lines	string	no	—	Comma-separated account numbers. Omit for all of them.
since	string (RFC 3339)	no	—	Only count messages after this instant, RFC 3339.

Responses

200

Unread counts.

Field	Type	Description
total	integer	The sum across every line reported, so one badge cannot disagree with the per-line numbers.
lines	object[]
lines[].line	string
lines[].count	integer

{
  "data": {
    "total": 7,
    "lines": [
      {
        "line": "12125550188",
        "count": 5
      },
      {
        "line": "12125550199",
        "count": 2
      }
    ]
  }
}

Errors

Status	Meaning
400	invalid_request — a missing or malformed field, an unknown enum value, or an unknown field in the body. Nothing was charged.
401	unauthenticated — no credential, or one that is invalid, revoked or expired. The WWW-Authenticate header names the scope the endpoint wanted.
403	Two different failures share this status, and the type tells them apart:
500	internal_error — something failed on our side. For a send, nothing was charged, guaranteed, which is what makes a retry safe.

See Errors for the full catalog and what to do about each.

Example

curl -X GET 'https://api.account.telebroad.com/api/public/v1/sms/unread' \
  -H "Authorization: Bearer $TB_KEY"

Try it in the playground →