Guides

Direct messages

Read and answer DMs through the same normalised shape as everything else.

MCP equivalents are list_conversations, read_conversation, mark_conversation_read, and send_message. See the MCP guide.

Threads

GET /v1/conversations lists threads across every connected network that supports messaging, most recent first, with who is in each, the last message and an unread count.

Reading one

GET /v1/conversations/{id}/messages?account=acc_…. The account is required: a conversation id only means something on the connection it belongs to.

Each message carries fromMe, so you never have to compare handles to work out which side sent it.

Sending

curl -X POST https://api.postlake.dev/v1/conversations/CONVO_ID/messages \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9","text":"Thanks for getting in touch."}'

Links and mentions in the text are made real rather than left as plain characters. Messaging is free on supported networks except X, where sending a direct message costs 6 credits.

Starting a new one

You do not need to find a conversation id first. POST /v1/conversations with a handle finds or opens the thread and returns it.

curl -X POST https://api.postlake.dev/v1/conversations \
  -H "authorization: Bearer $POSTLAKE_KEY" \
  -H "content-type: application/json" \
  -d '{"account":"acc_7f3k9","handle":"alice.bsky.social"}'

Bluesky: tick the DM box

Bluesky app passwords only get direct-message access if the box was ticked when the password was created. It cannot be added afterwards. If DMs return a permission error, create a new app password with direct messages enabled and reconnect the channel.

Instagram: two switches, not one

Granting the permission is not enough. Instagram has a separate switch inside the app, and until it is on, every message call is refused. In the Instagram app open Settings, then Messages and story replies, then Connected tools, and turn on Allow access to messages. Meta's error for this sounds like a missing permission, so it sends people to app review for a setting only the account owner can change. If PostLake returns that error, we say which switch to flip.

Instagram also holds you to a reply window: you can answer within 24 hours of the person's last message, and no longer. A reply a person wrote can use the Human Agent tag, which extends that to 7 days. Send humanAgent: true only when a human actually composed the reply. An automated reply claiming otherwise is exactly what the tag exists to stop, and the penalty lands on the connected account rather than on the caller. Our MCP tools do not offer the flag for that reason.

What you cannot do, and why

Messaging is the most restricted thing any network offers. Bluesky is open. Meta requires app review and business accounts. X allows reading but its API sending has a history of account bans. LinkedIn messaging is partner-only. So this is per-network by nature rather than one universal inbox. Platform support shows where it works today.

Real-time delivery

Facebook and Instagram can push message.received webhooks to PostLake. X and Bluesky inboxes are available through the same REST, SDK, and MCP operations, but those networks do not push inbound messages to PostLake. Poll GET /v1/conversations or call list_conversations on a schedule for those accounts.