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 messageslet cancelled: number;do {  const result = await client.messages.cancel({ all: true });  cancelled = result.cancelled;} while (cancelled > 0);

The SDK calls DELETE /v2/messages. The equivalent raw request passes the message IDs as messageIds query parameters:

curl -X DELETE "https://qstash.upstash.io/v2/messages?messageIds=message-id-1&messageIds=message-id-2" \  -H "Authorization: Bearer <QSTASH_TOKEN>"

A successful request returns 200 with the number of messages cancelled:

{ "cancelled": 2 }

messageIds also accepts a single comma-separated value (messageIds=message-id-1,message-id-2).

Cancel messages with filters#

import { Client } from "@upstash/qstash";const client = new Client({ token: "<QSTASH_TOKEN>" });// cancel messages matching a URL and labellet cancelled: number;do {  const result = await client.messages.cancel({    filter: {      url: "https://example.com",      label: "my-label",    }  });  cancelled = result.cancelled;} while (cancelled > 0);

Note

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