Messaging APIAPI

Direct messages on every network, from your own code

FoPost keeps each DM thread from your connected accounts in one place. List conversations, start new ones, message a segment of your contacts at once, or drip a series of messages over days, all with the same API key.

Get your API keyRead the docs
GET /v1/inbox/conversations
curl "https://api.fopost.com/v1/inbox/conversations?workspace_id=9b2f6c1e-..." \
  -H "X-API-Key: $API_KEY"

{
  "data": [
    {
      "workspace_id": "9b2f6c1e-...",
      "account_id": "4a71d80b-...",
      "conversation_id": "t_1029384756",
      "message_count": 6,
      "unread_count": 2,
      "last_message_at": "2026-11-10T16:42:08Z",
      "last_message_text": "Is the large size back in stock?",
      "last_message_outbound": false,
      "participant": { "name": "Jordan P.", "handle": "jordanp", "avatar_url": "https://..." },
      "account": { "id": "4a71d80b-...", "platform": "instagram", "username": "yourbrand" }
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

One thread list

Every DM conversation from every connected account, latest first.

Broadcasts

One message into the existing threads of a filtered set of contacts.

Sequences

A series of messages, each sent a set number of hours after the last.

Conversations

Read a thread, answer it, or open a new one

Reply inside an existing thread with POST /v1/inbox/:id/reply. Start a new conversation by handle on X, Mastodon, Reddit, and Slack, or pass comment_id to answer an Instagram or Facebook comment privately. On Facebook and Instagram you can also show a typing indicator, and on Messenger hand a thread to another app and take it back.

Read the conversations reference
POST /v1/inbox/conversations
curl -X POST https://api.fopost.com/v1/inbox/conversations \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "4a71d80b-...",
    "handle": "jordanp",
    "text": "Thanks for the order. Your tracking link is on its way."
  }'

{ "conversation_id": "t_1029384756", "item": { "id": "2c9d4e81-...", "type": "dm", ... } }

Text and media

Up to 10 media ids from your library ride along where the network allows.

Typing and handover

POST /v1/inbox/conversations/:id/typing and /handover for Meta conversations.

X Chat

Encrypted X conversations pass through as ciphertext; the key stays in the browser.

Broadcasts

Message a segment without breaking platform rules

A broadcast goes into the conversations your account already has with a set of contacts, filtered by network, label, source, or custom field. Facebook, Instagram, and WhatsApp only allow a business message within 24 hours of the contact’s last one, so recipients outside that window are skipped with a reason, never attempted. On WhatsApp an approved template can reach past it.

See the broadcasts reference
POST /v1/broadcasts/:id/send
curl -X POST https://api.fopost.com/v1/broadcasts \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "9b2f6c1e-...",
    "account_id": "4a71d80b-...",
    "name": "Restock, November",
    "text": "The large size is back in stock this week.",
    "audience": { "platforms": ["instagram"], "label_ids": ["d41e7a90-..."] }
  }'

curl -X POST https://api.fopost.com/v1/broadcasts/8e2a5c13-.../send -H "X-API-Key: $API_KEY"

{ "id": "8e2a5c13-...", "status": "sending", "recipients": 212 }

Send now or later

Set scheduled_at to queue it, or cancel before it goes out.

Per-recipient result

GET /v1/broadcasts/:id/recipients shows sent, skipped, or failed, and why.

Sent once

Each recipient is claimed before sending, so a retry never messages twice.

Sequences

Follow up over days, automatically

A sequence is a list of up to 20 steps, each a message and a delay in hours after the previous one. Enroll contacts by id or by the same audience filter a broadcast uses, and unenroll them at any time. A step that falls outside the messaging window is skipped and the sequence carries on.

See the sequences reference
POST /v1/sequences/:id/enroll
curl -X POST https://api.fopost.com/v1/sequences/5b9c2e40-.../enroll \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": ["a7f3c2d1-..."] }'

{ "id": "5b9c2e40-...", "enrolled": 1 }

Pause any time

Set status to paused and no further steps go out until you resume.

Unenroll

POST /v1/sequences/:id/unenroll stops a contact immediately.

Enrollment counts

Active, completed, stopped, and failed, per sequence.

Contacts

Know who you are talking to

People who message your accounts become contacts automatically. Add more by hand or import a CSV of up to 5,000 rows with a platform and a handle column. Define up to 50 custom fields per workspace (text, number, date, select, or yes/no) and filter broadcasts and sequences on them.

Start building
Connected accounts across every network in one workspace

CSV import

POST /v1/contacts/import returns created, merged, and skipped rows with reasons.

Custom fields

Columns that match a field key are filled in on import.

Full history

GET /v1/contacts/:id/conversations lists what each contact wrote.

Messaging API questions, answered

Which networks can I message?

Conversations are read from Bluesky, Facebook, Instagram, Mastodon, Reddit, Slack, Telegram, WhatsApp, and X where the account has granted messaging permission. Starting a new conversation by handle works on X, Mastodon, Reddit, and Slack.

What is the messaging window?

Facebook, Instagram, and WhatsApp accept a business message only within 24 hours of the contact’s last message. Broadcasts and sequences check it before every send and skip anyone outside it, with the reason recorded.

Which API key scopes do I need?

Reading conversations, contacts, broadcasts, and sequences needs the inbox scope. Anything that puts a message on a network, such as sending a broadcast or enrolling a contact, also needs publish.

Can a broadcast message people who never wrote to us?

No. A broadcast lands in a conversation the account already has with the contact. Contacts with no conversation are skipped as never messaged.

Does anything send without my request?

A broadcast sends when you call send or at the time you scheduled. A sequence sends its steps after you enroll someone. Nothing is messaged that you did not set up.

Is there a rate limit?

Yes, 100 requests per minute per key. Networks also apply their own limits, and a refused send comes back with the network’s reason.

Build on the Messaging API today

Starting is free and the full API is included. Create a key and make your first call in minutes.

Get your API key