Skip to content
PostyAPIv0.3.81
Menu

API reference

Inbox

List inbox conversations

get/v1/inbox/conversations

List direct message conversations from connected social channels, newest activity first. Filter by status (open, archived or spam, default open) and channelId; days is clamped to the plan's inbox history window. Requires inbox:view.

Query parameters

  • statusstring

    One ofopenarchivedspam

    Default "open"

  • channelIdstring

    Min length 1

  • daysinteger

    Default 30 · Min 1 · Max 365

  • limitinteger

    Default 25 · Min 1 · Max 100

  • starting_afterstring

Response 200

One page of conversations

  • objectstringrequired

    One oflist

  • dataarray of InboxConversationrequired
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
  • unreadTotalintegerrequired
  • windowDaysintegerrequired

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
Request
curl "https://api.posty.social/v1/inbox/conversations" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "channelId": "string",
      "platform": "bluesky",
      "externalConversationId": "string",
      "participant": {
        "id": "string",
        "name": "string",
        "username": "string",
        "avatarUrl": "string"
      },
      "lastMessageText": "string",
      "lastMessageAt": "2026-01-15T09:30:00.000Z",
      "lastReadAt": "2026-01-15T09:30:00.000Z",
      "participantLastReadAt": "2026-01-15T09:30:00.000Z",
      "participantLastDeliveredAt": "2026-01-15T09:30:00.000Z",
      "unreadCount": 1,
      "status": "open",
      "standby": true,
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "channel": {
        "name": "string",
        "platform": "bluesky",
        "avatarUrl": "string"
      }
    }
  ],
  "has_more": true,
  "next_cursor": "string",
  "unreadTotal": 1,
  "windowDays": 1
}

List conversation messages

get/v1/inbox/conversations/{id}/messages

List messages in one inbox conversation, newest first, with the conversation itself. Pass next_cursor as starting_after to page back through older messages. Reading does not mark the conversation read. Requires inbox:view.

Path parameters

  • idstringrequired

    Min length 1

Query parameters

  • limitinteger

    Default 50 · Min 1 · Max 100

  • starting_afterstring

Response 200

One page of messages

  • objectstringrequired

    One oflist

  • dataarray of InboxMessagerequired
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
  • conversationInboxConversationrequired

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
404
Not found in this workspace
Request
curl "https://api.posty.social/v1/inbox/conversations/$ID/messages" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "id": "string",
      "conversationId": "string",
      "externalMessageId": "string",
      "fromParticipant": true,
      "senderName": "string",
      "messageText": "string",
      "attachmentType": "string",
      "attachmentUrl": "string",
      "content": {
        "unsupported": true,
        "sender": {
          "id": "string",
          "name": "string",
          "username": "string",
          "email": "string"
        },
        "recipients": [
          {
            "id": null,
            "name": null,
            "username": null,
            "email": null
          }
        ],
        "attachments": [
          {
            "id": null,
            "kind": null,
            "name": null,
            "url": null,
            "previewUrl": null,
            "width": null,
            "height": null,
            "duration": null,
            "template": null
          }
        ],
        "shares": [
          {
            "id": null,
            "name": null,
            "description": null,
            "type": null,
            "url": null,
            "template": null
          }
        ],
        "story": {
          "id": "string",
          "url": "string"
        },
        "reactionsObservedAt": "2026-01-15T09:30:00.000Z",
        "reactions": [
          {
            "emoji": null,
            "users": null
          }
        ],
        "tags": [
          {
            "id": null,
            "name": null
          }
        ]
      },
      "reaction": "string",
      "editedAt": "2026-01-15T09:30:00.000Z",
      "sentAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string",
  "conversation": {
    "id": "string",
    "channelId": "string",
    "platform": "bluesky",
    "externalConversationId": "string",
    "participant": {
      "id": "string",
      "name": "string",
      "username": "string",
      "avatarUrl": "string"
    },
    "lastMessageText": "string",
    "lastMessageAt": "2026-01-15T09:30:00.000Z",
    "lastReadAt": "2026-01-15T09:30:00.000Z",
    "participantLastReadAt": "2026-01-15T09:30:00.000Z",
    "participantLastDeliveredAt": "2026-01-15T09:30:00.000Z",
    "unreadCount": 1,
    "status": "open",
    "standby": true,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "channel": {
      "name": "string",
      "platform": "bluesky",
      "avatarUrl": "string"
    }
  }
}

Update conversation status

patch/v1/inbox/conversations/{id}

Move an inbox conversation to open, archived or spam. Archived and spam conversations leave the open list until moved back. Nothing is sent to the social platform. Requires inbox:view.

Path parameters

  • idstringrequired

    Min length 1

Request body

  • statusstringrequired

    One ofopenarchivedspam

Response 200

The conversation's new state

  • idstringrequired
  • statusstringrequired

    One ofopenarchivedspam

  • unreadCountintegerrequired
  • lastReadAtstring (date-time)requirednullable
  • updatedAtstring (date-time)required

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
404
Not found in this workspace
Request
curl -X PATCH "https://api.posty.social/v1/inbox/conversations/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "open"
}'
Response 200
{
  "id": "string",
  "status": "open",
  "unreadCount": 1,
  "lastReadAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Mark conversation read

post/v1/inbox/conversations/{id}/read

Mark an inbox conversation read for the workspace team, clearing its unread count. It does not send a seen receipt to the social platform. Requires inbox:view.

Path parameters

  • idstringrequired

    Min length 1

Response 200

The conversation's new state

  • idstringrequired
  • statusstringrequired

    One ofopenarchivedspam

  • unreadCountintegerrequired
  • lastReadAtstring (date-time)requirednullable
  • updatedAtstring (date-time)required

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
404
Not found in this workspace
Request
curl -X POST "https://api.posty.social/v1/inbox/conversations/$ID/read" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "id": "string",
  "status": "open",
  "unreadCount": 1,
  "lastReadAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

List inbox post threads

get/v1/inbox/post-threads

List published posts whose platform comments appear in the inbox, newest first. Filter by channelId; days is clamped to the plan's inbox history window. Use get_post_comment_thread with a thread id to read its comments. Requires inbox:view.

Query parameters

  • channelIdstring

    Min length 1

  • daysinteger

    Default 30 · Min 1 · Max 365

  • limitinteger

    Default 30 · Min 1 · Max 100

Response 200

Published post threads

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
Request
curl "https://api.posty.social/v1/inbox/post-threads" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "data": [
    {
      "id": "string",
      "postId": "string",
      "channelId": "string",
      "platform": "bluesky",
      "externalPostId": "string",
      "permalink": "string",
      "postTitle": "string",
      "postBody": "string",
      "mediaUrl": "string",
      "publishedAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "channel": {
        "name": "string",
        "platform": "bluesky",
        "avatarUrl": "string"
      }
    }
  ],
  "windowDays": 1
}

Get post comment thread

get/v1/inbox/post-threads/{id}

Read one published post's platform comment thread as a flat list, oldest first, with parentCommentId linking replies. Facebook, Instagram and Threads comments are available; YouTube and Bluesky threads report commentStatus not_mirrored. Requires inbox:view.

Path parameters

  • idstringrequired

    Min length 1

Response 200

The post and its stored comments

Errors

400
Invalid request
401
Unauthenticated
403
Missing the inbox permission
404
Not found in this workspace
Request
curl "https://api.posty.social/v1/inbox/post-threads/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"
Response 200
{
  "thread": {
    "id": "string",
    "postId": "string",
    "channelId": "string",
    "platform": "bluesky",
    "externalPostId": "string",
    "permalink": "string",
    "postTitle": "string",
    "postBody": "string",
    "mediaUrl": "string",
    "publishedAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z",
    "channel": {
      "name": "string",
      "platform": "bluesky",
      "avatarUrl": "string"
    }
  },
  "comments": [
    {
      "id": "string",
      "parentCommentId": "string",
      "authorId": "string",
      "authorName": "string",
      "authorUsername": "string",
      "authorAvatarUrl": "string",
      "isFromConnectedAccount": true,
      "likeCount": 1,
      "messageText": "string",
      "createdAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "commentStatus": {
    "type": "available",
    "message": "string"
  }
}

Models

Objects referenced by the endpoints above.

InboxCommentStatus

  • typestringrequired

    One ofavailablenot_mirrored

  • messagestringrequirednullable

InboxConversation

  • idstringrequired
  • channelIdstringrequired
  • platformstringrequired

    One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

  • externalConversationIdstringrequired
  • participantobjectrequired
    Child attributes
    • idstringrequirednullable
    • namestringrequirednullable
    • usernamestringrequirednullable
    • avatarUrlstringrequirednullable
  • lastMessageTextstringrequirednullable
  • lastMessageAtstring (date-time)requirednullable
  • lastReadAtstring (date-time)requirednullable
  • participantLastReadAtstring (date-time)requirednullable
  • participantLastDeliveredAtstring (date-time)requirednullable
  • unreadCountintegerrequired
  • statusstringrequired

    One ofopenarchivedspam

  • standbybooleanrequired
  • createdAtstring (date-time)required
  • updatedAtstring (date-time)required
  • channelobjectrequired
    Child attributes
    • namestringrequired
    • platformstringrequired

      One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

    • avatarUrlstringrequirednullable

InboxMessage

  • idstringrequired
  • conversationIdstringrequired
  • externalMessageIdstringrequirednullable
  • fromParticipantbooleanrequired
  • senderNamestringrequirednullable
  • messageTextstringrequirednullable
  • attachmentTypestringrequirednullable
  • attachmentUrlstringrequirednullable
  • contentobjectrequired
    Child attributes
    • unsupportedboolean
    • senderobject
      Child attributes
      • idstring
      • namestring
      • usernamestring
      • emailstring
    • recipientsarray of object
      Child attributes
      • idstring
      • namestring
      • usernamestring
      • emailstring
    • attachmentsarray of object
      Child attributes
      • idstring
      • kindstringrequired
      • namestring
      • urlstring
      • previewUrlstring
      • widthnumber
      • heightnumber
      • durationnumber
      • templateobject
        Child attributes
        • titlestring
        • subtitlestring
        • imageUrlstring
        • buttonsarray of object
          Child attributes
          • titlestring
          • typestring
          • urlstring
          • payloadstring
    • sharesarray of object
      Child attributes
      • idstring
      • namestring
      • descriptionstring
      • typestring
      • urlstring
      • templatestring or object
        Option 2
        • titlestring
        • subtitlestring
        • imageUrlstring
        • buttonsarray of object
          Child attributes
          • titlestring
          • typestring
          • urlstring
          • payloadstring
    • storyobject
      Child attributes
      • idstring
      • urlstring
    • reactionsObservedAtstring (date-time)
    • reactionsarray of object
      Child attributes
      • emojistringrequired
      • usersarray of objectrequired
        Child attributes
        • idstring
        • namestring
        • usernamestring
        • emailstring
    • tagsarray of object
      Child attributes
      • idstring
      • namestring
  • reactionstringrequirednullable
  • editedAtstring (date-time)requirednullable
  • sentAtstring (date-time)required

InboxPostComment

  • idstringrequired
  • parentCommentIdstringrequirednullable
  • authorIdstringrequirednullable
  • authorNamestringrequirednullable
  • authorUsernamestringrequirednullable
  • authorAvatarUrlstringrequirednullable
  • isFromConnectedAccountbooleanrequired
  • likeCountintegerrequirednullable
  • messageTextstringrequirednullable
  • createdAtstring (date-time)requirednullable

InboxPostThread

  • idstringrequired
  • postIdstringrequired
  • channelIdstringrequired
  • platformstringrequired

    One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

  • externalPostIdstringrequired
  • permalinkstringrequirednullable
  • postTitlestringrequired
  • postBodystringrequirednullable
  • mediaUrlstringrequirednullable
  • publishedAtstring (date-time)requirednullable
  • updatedAtstring (date-time)required
  • channelobjectrequired
    Child attributes
    • namestringrequired
    • platformstringrequired

      One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube

    • avatarUrlstringrequirednullable