MsgMesh Docs

Concepts · delivery guarantees · how to connect ・ public beta

MsgMesh is a managed durable event bus: publish once, and people and AI receive it together. If the other side is offline, the message is kept — they can catch up later and replay it. Queuing, retries, backfill, reconnect: the platform handles that plumbing.

This page is about the mental model and the semantics — what each noun means, which of the four receive modes fits what, and what "at-least-once" actually looks like in your code. For per-endpoint request/response shapes see the API reference; to start typing, Quick start has copy-pasteable snippets.

1.Core concepts

The whole system has four nouns. Get these straight and the rest follows:

Noun	What it is
topic	A named stream of messages, e.g. `orders`, `chat`. Publishing and subscribing both happen per topic. Topics belong to your tenant and are isolated from everyone else's.
message	A payload in whatever shape you choose (usually JSON). The platform does not interpret it — it only delivers it reliably and keeps it until the retention window ends.
room	A routing label inside a topic — split one `chat` topic into `room-42`, `room-43`, and so on. It decouples "number of rooms" from "number of topics".
key / token	Your credential. Long-lived API keys stay server-side; browsers only ever hold a short-lived token your backend mints for them.

There are no queues, exchanges, or bindings to design up front — create a topic and start publishing.

2.Four ways to receive

One topic can be consumed several ways at once. What differs is who initiates, and how long the connection lives:

Mode	Good for	Watch out
Long-polling	Backend services, batch processing, environments before Node 22. A consumer group tracks progress, so a restart picks up where it left off.	It is a whole-topic firehose — it cannot receive just one room.
SSE	Live updates in a browser. The native `EventSource` reconnects on its own, so you can connect without installing anything.	Receive-only; publishing goes over ordinary HTTP.
WebSocket	When a middlebox blocks SSE, or you already run WebSocket infrastructure.	No native reconnect — use the official SDK, which already handles backoff and token rotation.
Webhook	When you want the platform to call your HTTPS endpoint and hold no long connection at all.	The target must be a publicly reachable https URL; anything pointing inward is rejected (below). An endpoint that is temporarily down is retried; one that answers with a permanent rejection such as `404` is not retried and is dead-lettered on the first attempt (below).

When a delivery fails: when the endpoint answers with a status code that a resend cannot change — 400, 404, 405, 410, 413, 414, 415, 422, 501 — there is no retry: the message is dead-lettered on the first attempt, rather than hammering your service with a payload it has already refused. Everything outside those nine codes counts as temporary and is retried a few times, and only dead-lettered if it still will not go through — timeouts, connection failures, every other 5xx, and codes such as 401, 403, 408, 409 and 429 all land in that bucket. 401 and 403 are deliberately counted as temporary, because they show up routinely during a rolling deploy or a signing-secret rotation, while the webhook itself is perfectly healthy.

So monitor the dead-letter queue, and do not treat retries as a deployment grace period. The retry count is a single digit and runs out quickly: when the endpoint refuses the connection outright (while it is restarting, say) the whole sequence takes seconds; when the endpoint accepts the connection but never answers, every attempt has to wait for its timeout, so the sequence takes about a minute. And a 404 — a new build that has not wired that route up yet, say — gets no retry at all.

A dead-lettered message can be inspected on the DLQ page in the panel, and replayed back into the main topic (the webhook itself stays enabled). Two things to know up front: inspecting is one-shot — once a batch of dead letters has been inspected it no longer shows up in later inspections (replay goes through a separate path and is unaffected, so those messages can still be replayed), so never read an empty inspection as “there are no dead letters”; and the dead-letter queue has a retention period of its own (currently 30 days, counted separately from your plan’s message retention), after which messages are deleted as well.

Webhook SSRF protection: the target is resolved at registration and rejected if it points at a private, loopback, or cloud-metadata address; at delivery time the actual IP is re-checked right before dialing (blocking DNS rebinding), and no redirect is ever followed. None of this can be turned off. A delivery stopped by this guard disables the webhook and records the reason — the message is not dead-lettered, it simply stays where it is. Once you correct the address and re-enable the webhook in the panel, delivery resumes from where it stopped, for the messages still inside your retention window (1 day on Free, 30 days on paid); anything older has already been deleted, and because this path deliberately skips the dead-letter queue, there is nowhere else to recover it from. Act on the suspension notice promptly. Note that a 308 that merely normalises a trailing slash still counts as a redirect: register the final URL directly.

3.Delivery guarantees: at-least-once, resume, dedupe

This is the section most worth reading to the end, because it decides whether your code has to handle duplicates.

At-least-once. The platform guarantees a message is not lost because you disconnected — it does not guarantee exactly one delivery. On reconnect the server backfills from where you left off, and at the boundary it will occasionally resend one or two you already saw.

Resume runs on a cursor. Every message carries a monotonically increasing <partition>-<offset> cursor. Your client remembers the last one it saw and sends it back on reconnect, and the server picks up from there — what you missed while disconnected is backfilled rather than dropped.

Deduping is the client's job — and the SDK already does it. The official SDKs (JavaScript and Python) dedupe per partition by cursor: an offset no greater than the highest already seen for that partition is skipped. So with the SDK, what reaches your onMessage is already duplicate-free.

When it cannot backfill, it says so. If you were gone longer than the server's replay window, it emits a msgmesh-resync signal, meaning "I cannot guarantee completeness". Fetch a fresh snapshot yourself; subsequent live messages dedupe against it by cursor.

Ordering. Publish order is preserved within a partition. To keep a group of messages strictly ordered, put them in the same room (a room is the partition key).

4.Credentials: server-side keys vs browser tokens

Long-lived API keys stay server-side. A key is shown in plaintext exactly once, at creation; after that the platform stores only a hash. Never commit one, never log one.

Never put an API key in a browser — anything in the frontend leaks. The right shape is a token broker: your backend holds the key, calls POST /v1/tokens, and hands the frontend a short-lived, downscoped token — so the frontend only ever holds something that expires. The official SDKs support this directly (give them a callback that fetches a token); caching, refetching before expiry, and rotating on reconnect are all handled for you.

Permissions come in two layers. Role keys are admin / producer / consumer; when you need finer control, capability keys spell out which operations × which topics × which rooms. Downscoping may only narrow, and overreach is rejected with 403.

5.Rooms: routing vs isolation

Rooms have two layers, and the distinction matters because the first one alone provides no security:

① Routing (filtering). Publish with a room key and subscribe with a room, and you receive only that room. Omitting the room receives the whole topic (backward compatible).

② Isolation (platform-enforced). Name the allowed rooms in the credential's capabilities and the platform enforces that it can only send and receive those rooms, returning 403 on overreach.

6.Errors and status codes

Any non-2xx response returns {"error": "..."}; the SDKs raise a typed error you can match with instanceof.

Status	Meaning	What to do
`400` / `422`	Invalid arguments or body	Fix the request. Retrying is pointless.
`401`	Credential invalid or gone	Terminal. Obtain a new credential; do not retry indefinitely.
`403`	Insufficient scope, or a billing suspension	Possibly recoverable (topping up lifts a suspension automatically) — back off and retry.
`404`	Resource does not exist	Check the name. With the strict topic gate on, a topic that was never created is also a 404.
`429`	Rate limit or included quota exceeded	Back off and retry; if it persists, it is time to change plan.

5xx responses carry a request_id — include it when reporting a problem and it can be traced directly.

7.Connect in three minutes

npm i @msgmesh/sdk        # JavaScript / TypeScript
pip install msgmesh        # Python (same API, snake_case)

import { MsgMesh } from "@msgmesh/sdk";

const mq = new MsgMesh({
  apiKey: process.env.MSGMESH_KEY,   // long-lived key, server-side only
  controlPlaneUrl: "...", gatewayUrl: "...", realtimeUrl: "...",
});

await mq.createTopic("orders");
await mq.publish("orders", { hello: 1 });
const msgs = await mq.poll("orders", { group: "g1" });

You do not need the SDK — it is all ordinary HTTP: send Authorization: Bearer <key> to the matching endpoint. Shapes are in the API reference.

8.For AI agents (MCP)

MsgMesh ships an official MCP server, so any MCP-capable AI tool (Claude Code, for example) can treat an event stream as an input source: the agent waits on watch_topic, wakes when something is published, receives only the new events, and decides what to do.

npx @msgmesh/mcp-server     # only MQ_API_KEY is required

This is not "have the agent poll every minute" — it is woken by events, so it neither spins idly nor misses what happened in between.

9.Next steps

Quick start — copy-pasteable snippets (SDK / curl / MCP config).
API reference — request and response shapes for every endpoint.
Live demo — no sign-up; open it and watch events flow.
Official examples — full projects you can clone and run.
Pricing — plans and quotas. Free during public beta; final pricing is not yet set.

Questions, or want help connecting? Email [email protected].

This document describes MsgMesh's behaviour during public beta and may be updated as the service evolves. The authoritative per-endpoint reference is the API reference. Where the Chinese and English versions differ, the Chinese version governs.