Inbox

List conversations, read messages, and send text replies through a connected Bluesky account.

The Inbox API provides programmatic access to direct messages on a connected Bluesky account. List conversations, read message histories, and send text replies, all scoped to a single connection. Media attachments are not supported by Bluesky's Chat API.

List Conversations

Returns the conversations for the connected account, ordered by most recent activity:

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.listInboxConversations({
  accountId: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  limit: 50,
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convos": [
    {
      "id": "3k7x...",
      "members": [
        {
          "id": "did:plc:alice",
          "username": "alice.bsky.social",
          "displayName": "Alice"
        }
      ],
      "muted": false,
      "unreadCount": 2,
      "lastMessage": null
    }
  ],
  "cursor": null
}

Query	Required	Notes
`accountId`	Yes	Bluesky connection id
`limit`	No	1-100, default 50
`cursor`	No	Pagination cursor from the previous response

Each conversation includes its id, the members (DID, handle, and display name), the muted flag, an unreadCount, and a lastMessage preview.

Create Conversation

Starts a 1-1 conversation with a recipient. Accepts a handle or a DID:

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.createInboxConversation({
  createInboxConversationBody: {
    "accountId": "YOUR_BLUESKY_ACCOUNT_ID",
    "recipient": "alice.bsky.social"
  },
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convo": {
    "id": "3k7x...",
    "members": [
      {
        "id": "did:plc:alice",
        "username": "alice.bsky.social",
        "displayName": "Alice"
      }
    ],
    "muted": false,
    "unreadCount": 0,
    "lastMessage": null
  }
}

The recipient must accept messages from the connected account. Closed inboxes, follow requirements, and blocks fail with RECIPIENT_UNREACHABLE. The response is 201 Created with the conversation.

Read Messages

Returns the messages of a single conversation, newest first:

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.listInboxMessages({
  convoId: "3k7x...",
  accountId: "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  limit: 50,
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "convoId": "3k7x...",
  "messages": [
    {
      "id": "3k7y...",
      "text": "Hey, loved your latest post!",
      "senderId": "did:plc:alice",
      "sentAt": "2026-09-08T12:00:00.000Z",
      "attachments": []
    }
  ],
  "cursor": null
}

Parameter	Required	Notes
`convoId`	Yes	Conversation id from the list above
`accountId`	Yes	Bluesky connection id
`limit`	No	1-100, default 50
`cursor`	No	Pagination cursor from the previous response

Deleted messages are returned with text: null.

Send Message

Sends a text message to a conversation. Text only, up to 1,000 characters:

import { Configuration, InboxApi } from "@onepostly/sdk";

const inboxApi = new InboxApi(
  new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);

const response = await inboxApi.sendInboxMessage({
  sendInboxMessageBody: {
    "accountId": "YOUR_BLUESKY_ACCOUNT_ID",
    "convoId": "CONVERSATION_ID",
    "text": "Hey, loved your latest post!"
  },
});
console.log(response);

{
  "accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
  "message": {
    "id": "3k7y...",
    "text": "Hey, loved your latest post!",
    "senderId": "did:plc:you",
    "sentAt": "2026-09-08T12:00:00.000Z",
    "attachments": []
  }
}

The response is 201 Created with the sent message (id, text, senderId, sentAt).

Errors

Code	Cause	Fix
`CONVO_NOT_FOUND`	Unknown conversation id	List conversations and pass a valid id
`RECIPIENT_NOT_FOUND`	Unknown handle or DID	Verify the recipient
`RECIPIENT_UNREACHABLE`	DMs disabled, follow required, or blocked	The recipient must accept messages
`CONVO_LOCKED`	The conversation is locked	Messages cannot be sent to a locked conversation
`TEXT_REQUIRED`	Empty message text	Provide message text
`TEXT_TOO_LONG`	Over 1,000 characters	Shorten the text
`TOKEN_INVALID`	App Password revoked or session expired	Create a new App Password and reconnect
`CONNECTION_INACTIVE`	Connection is not active	Reconnect the account
`INBOX_FAILED`	Bluesky chat request failed	Retry later

List Conversations

Create Conversation

Read Messages

Send Message

Errors

See Also

On this page