Skip to Content

Inbox

Messages taken in from the hosts' channels.

OperationKindHTTP
inbox.listcallGET /v1/inbox
inbox.followstreamGET /v1/inbox
inbox.donecallPOST /v1/inbox/{host}/{id}/done
inbox.reopencallDELETE /v1/inbox/{host}/{id}/done

inbox.list

Messages taken in from the hosts' channels.

Needs the role view.

Arguments

NameWhereRequiredDescription
hostquerynoOnly this host.
topicquerynoOnly topics starting with this.
beforequerynoOnly messages taken in before this seq.
donequerynoOnly done ones, or only those that are not.
limitquerynoAt most this many (default 100, at most 1,000).

Result

FieldTypeDescription
messagesInboxMessage[]
next (optional)integer | nullPass as before for older ones, when there are more.
Request
{
  "id": 1,
  "op": "inbox.list"
}
Reply
{
  "id": 1,
  "result": {
    "messages": [
      {
        "body": {
          "columns": 2
        },
        "from": {
          "level": "host",
          "session": "k3v9qz2m8w1x",
          "uid": 1001
        },
        "id": 0,
        "keep": "none",
        "time": "2026-11-12T09:30:00Z",
        "topic": "myplugin/progress",
        "done": true,
        "host": "studio",
        "host_id": "text",
        "seq": 0
      }
    ],
    "next": 0
  }
}

inbox.follow

Messages as they are taken in from the hosts.

A stream, as a subscription on the portal or a WebSocket of its own. It does not resume. Needs the role view.

Arguments

NameWhereRequiredDescription
hostquerynoOnly this host.
topicquerynoOnly topics starting with this.

Frames from the server

FrameKindDescription
messageJSONA stored message with its host. Example: {"body":{},"done":false,"from":{"level":"agent","uid":1001},"host":"server","id":4812,"keep":"log","time":"2026-11-12T10:00:00Z","topic":"myplugin/progress"}
droppedJSONThis follower was too slow. events counts the server's events it missed, of every kind. Read the inbox again. Example: {"dropped":{"events":12}}
Request
{
  "id": 1,
  "op": "inbox.follow"
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "body": {},
    "done": false,
    "from": {
      "level": "agent",
      "uid": 1001
    },
    "host": "server",
    "id": 4812,
    "keep": "log",
    "time": "2026-11-12T10:00:00Z",
    "topic": "myplugin/progress"
  }
}

End the subscription with {"sub": 1, "end": true}.

inbox.done

Mark a message as done.

Needs the role operate.

Arguments

NameWhereRequiredDescription
hostpathyesThe host it came from, by its name or its id
idpathyesThe message's id on that host

Result

FieldTypeDescription
okboolean

Errors

StatusWhen
404No such message
Request
{
  "id": 1,
  "op": "inbox.done",
  "args": {
    "host": "studio",
    "id": 42
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

inbox.reopen

Mark a message as open again.

Needs the role operate.

Arguments

NameWhereRequiredDescription
hostpathyesThe host it came from, by its name or its id
idpathyesThe message's id on that host

Result

FieldTypeDescription
okboolean

Errors

StatusWhen
404No such message
Request
{
  "id": 1,
  "op": "inbox.reopen",
  "args": {
    "host": "studio",
    "id": 42
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

Types

The named types used on this page.

InboxMessage

A stored message: the host's message with where it came from.

InboxMessage

A stored message: the host's message with where it came from.

On this page