Inbox

The inbox gathers what people say about a profile’s accounts. Lists take the profileId; actions take the accountId each item belongs to. Inbox ids (thr_…, cmt_…, mtn_…, cnv_…, rev_…) are opaque and only valid in your workspace: keep them and send them back as they are.

Comments

First, the recent posts with comments, including those published outside Marsial:

curl

curl "https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/posts?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Then the comments of one of them, with their nested replies. Each comment says in can what its network allows: reply, delete, hide or like.

curl

curl "https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/posts/thr_…/comments?accountId=acc_3k9x2m",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

To reply under a comment, send its id as commentId; without it, you comment on the post:

curl

curl -X POST "https://api.marsial.dev/v1/inbox/posts/thr_…/comments" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "Thanks, Luis!",
    "commentId": "cmt_…"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/posts/thr_…/comments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "Thanks, Luis!",
    "commentId": "cmt_…"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/posts/thr_…/comments",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "Thanks, Luis!",
        "commentId": "cmt_…"
    },
)
data = res.json()["data"]

To hide or like it, PATCH with hidden or liked; to delete it, DELETE. To hear about every new comment instead, subscribe to comment.received in webhooks.

Mentions

Posts and comments by other people that tag your accounts, from the last 7 days:

• Instagram: when you are tagged in a comment (kind: "comment") or in their post’s caption (kind: "caption"). Only accounts connected through Facebook. Instagram sends the text a moment later: until then, content is empty.
• LinkedIn: when your page is mentioned in a post (kind: "post"), with its url.

curl

curl "https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/mentions?profileId=prf_8f2k4d",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

200 OK

{
  "data": {
    "items": [
      {
        "id": "mtn_…",
        "accountId": "acc_3k9x2m",
        "platform": "instagram",
        "kind": "comment",
        "content": "Look what just arrived from @acme!",
        "author": { "username": "lucia" },
        "publishedAt": "2026-10-25T09:12:00.000Z",
        "canReply": true
      }
    ],
    "nextCursor": null
  }
}

Instagram mentions can be answered (canReply: true): under the comment that tagged you, or as a comment on the post that did.

curl

curl -X POST "https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "Thanks for sharing, Lucía!"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "Thanks for sharing, Lucía!"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/mentions/mtn_…/reply",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "Thanks for sharing, Lucía!"
    },
)
data = res.json()["data"]

Caution

Replying posts a public comment on the network, on behalf of the account. Test with a test account of your own, never a customer’s.

Direct messages

Instagram, Facebook, X, Bluesky and Telegram. On X only unencrypted messages are available.

curl

curl "https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/conversations?profileId=prf_8f2k4d&status=active",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

A conversation’s messages, newest first (follow cursor for older ones):

curl

curl "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

Replying returns 201 with the message’s id (or null when the network gives none):

curl

curl -X POST "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hi! Yes, we still have it in M."
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "text": "Hi! Yes, we still have it in M."
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/conversations/cnv_…/messages",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "text": "Hi! Yes, we still have it in M."
    },
)
data = res.json()["data"]

A conversation id already carries its account, so these calls need no accountId. Only cnv_… ids stored before 27 October 2026 still ask for it.

Caution

Instagram and Facebook only let you answer within 24 hours of the person’s last message. After that, the API returns an error saying why.

Mark a conversation as read with POST …/read and archive or reopen it with PATCH and status (archived or active). To hear about every new message as it arrives, subscribe to message.received in webhooks.

Reviews

Google Business (1 to 5 stars) and Facebook (recommends or not). hasReply=false keeps only those still waiting for an answer.

curl

curl "https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false" \
  -H "Authorization: Bearer $MARSIAL_API_KEY"

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false', {
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
  },
});
const { data } = await res.json();

Python

import os, requests

res = requests.get(
    "https://api.marsial.dev/v1/inbox/reviews?profileId=prf_8f2k4d&hasReply=false",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
)
data = res.json()["data"]

curl

curl -X POST "https://api.marsial.dev/v1/inbox/reviews/rev_…/reply" \
  -H "Authorization: Bearer $MARSIAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "acc_3k9x2m",
    "text": "Thanks for coming, Marta!"
  }'

Node

const res = await fetch('https://api.marsial.dev/v1/inbox/reviews/rev_…/reply', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MARSIAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "accountId": "acc_3k9x2m",
    "text": "Thanks for coming, Marta!"
  }),
});
const { data } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.marsial.dev/v1/inbox/reviews/rev_…/reply",
    headers={"Authorization": f"Bearer {os.environ['MARSIAL_API_KEY']}"},
    json={
        "accountId": "acc_3k9x2m",
        "text": "Thanks for coming, Marta!"
    },
)
data = res.json()["data"]

To delete your answer, DELETE the same path with accountId. New reviews arrive by webhook as review.received.