List messages in a conversation
Returns the messages PostZen holds for one thread, oldest first by default, refreshing them from the platform when the stored copy is stale. Strictly read-only: it never marks the thread read — use POST /v1/inbox/conversations/{conversationId}/read for that. Meta returns full content only for roughly the twenty newest Instagram messages, so older ones may carry an id and timestamp without text or attachments. Read-only and read-write API keys are accepted.
Authorization
bearerAuth PostZen API key.
In: header
Path Parameters
The platform's own conversation (thread) id, as returned in id by the list and search endpoints — not a PostZen document id.
Query Parameters
PostZen account id that owns the conversation.
Page size.
Opaque pagination cursor from pagination.nextCursor. A malformed cursor is a 400.
Order by send time.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/inbox/conversations/string/messages?accountId=string"{ "status": "ok", "pagination": { "hasMore": false, "nextCursor": null }, "sortOrderApplied": "asc", "messages": [ { "id": "aWdfZGFtOm1zZ18w", "conversationId": "t_17845791234567890", "accountId": "k17d8s9f0a1b2c3d4e5f6g7h8i", "platform": "instagram", "message": "The sale runs through Friday.", "senderId": "17841411111111111", "senderName": "postzenhq", "direction": "outgoing", "createdAt": "2026-08-17T09:12:44.000Z" }, { "id": "aWdfZGFtOm1zZ18x", "conversationId": "t_17845791234567890", "accountId": "k17d8s9f0a1b2c3d4e5f6g7h8i", "platform": "instagram", "message": "Is the sale still on?", "senderId": "17841400000000000", "senderName": "Jane Doe", "direction": "incoming", "createdAt": "2026-08-18T16:04:11.000Z" } ], "lastUpdated": "2026-08-18T16:10:00.000Z"}{ "error": "Direct messages support Instagram accounts only.", "code": "platformUnsupported", "platform": "tiktok"}{ "error": "Unauthorized"}{ "error": "Reconnect the account to grant PostZen access to its messages.", "code": "platformCapabilityMissing", "platform": "instagram"}{ "error": "That conversation could not be found.", "code": "conversationNotFound"}{ "error": "This connection needs to be reauthorized before its messages can be read.", "code": "connectionDead"}{ "error": "rate_limited", "retryAfter": 30}{ "error": "Failed to create post"}Mark a conversation read POST
Moves the thread’s local read watermark to its newest synced message and returns how many incoming messages crossed from unread to read. Nothing is sent to the platform, and reading messages never does this implicitly. Requires a read-write API key.
Send a direct message POST
Sends a message into an existing thread. The recipient is the other participant on that thread, so no recipient id is needed. Exactly one of `message` or `attachmentUrl` may be sent per call — Meta's Send API carries one payload at a time, so combining them is a 400. Meta only accepts replies within 24 hours of the person's last message; outside that window the platform refuses the send and PostZen reports `400 PLATFORM_LIMITATION` with Meta's own envelope attached. Sends are hard-gated on the account's messaging scope. Requires a read-write API key.