Skip to content

Mark a conversation read

POST
/account/messages/{peer_ref}/read

Marks every unread message the account peer_ref has sent you as read, and returns how many this request marked.

You need to be signed in; no capability is needed. Without a session cookie or bearer token that identifies you, the answer is 401, whether or not public mode is on. A peer_ref that isn’t a whole number gets a plain-text 400 before sign-in is checked. The account isn’t looked up and nothing else is checked, so the answer is 200 even for a peer_ref with no account, and marked_count is 0 only when no unread message from that peer_ref to you was found. Messages kept from an account that has been removed can still be marked. Your own peer_ref always gives 0, and a second request gives 0 unless new messages from that person arrived in between.

Messages are marked whether or not you have loaded them, with the time of this request rather than when you saw them, and the sender sees that time as read_at. Messages already marked keep their earlier time. A message that arrives while the request runs can stay unread, and when two requests run at the same moment no message is counted twice, so one can mark them all and the other 0. A 200 doesn’t mean nothing is unread afterwards.

When at least one message is marked, servers are asked to drop their cached unread count (see getMyUnreadDirectMessageCount). Nobody is notified. Server errors get a plain-text 500.

peer_ref
required
integer format: int64

The account whose messages to you to mark read.

How many messages this request marked read.

object
marked_count
required

How many messages this request marked read; 0 when there were none.

integer format: int64

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}