Messages - Upstash Documentation

Messages are removed from the database shortly after they're delivered, so you will not be able to retrieve a message after. This endpoint is intended to be used for accessing messages that are in the process of being delivered/retried.

Retrieve a message#

import { Client } from "@upstash/qstash";const client = new Client({ token: "<QSTASH_TOKEN>" });const messages = client.messagesconst msg = await messages.get("msgId");

Cancel a message#

import { Client } from "@upstash/qstash";const client = new Client({ token: "<QSTASH_TOKEN>" });await client.messages.cancel("msgId");

Cancel multiple messages#

import { Client } from "@upstash/qstash";const client = new Client({ token: "<QSTASH_TOKEN>" });// cancel two messages at onceawait client.messages.cancel(["message-id-1", "message-id-2"])// cancel all pending messages in one callawait client.messages.cancel({ all: true });

Cancel messages with filters#

import { Client } from "@upstash/qstash";const client = new Client({ token: "<QSTASH_TOKEN>" });// cancel all pending messages matching both the URL and labelawait client.messages.cancel({  filter: {    url: "https://example.com",    label: "my-label",  },});

A filter-based cancellation, including { all: true }, runs as a tracked bulk action. The call waits for the action to finish. One call processes all matching pending messages; you do not need to loop until cancelled is zero.

For a message ID or an array of IDs, cancelled is the actual number of messages cancelled. For a filter-based request, it is a snapshot of matching in-progress messages when the request was accepted. It is not a progress counter or a signal to request another batch.

Warning

The legacy count option is deprecated and ignored by the server. It does not limit how many messages are cancelled. Use message IDs to cancel a specific set of messages, or filters to select the messages to cancel.

Note

client.messages.delete(), client.messages.deleteMany(), and client.messages.deleteAll() are deprecated. Use client.messages.cancel() instead.