Remove subscriptions

Unsubscribe yourself or other users from one or more streams.


Usage examples

curl -X "DELETE" \
    -d 'subscriptions=["Denmark"]'

You may specify the principals argument like so:

curl -X "DELETE" \
    -d 'subscriptions=["Denmark"]' \
    -d 'principals=[""]'

Note: Unsubscribing another user from a stream requires administrative privileges.

#!/usr/bin/env python3

import zulip

# Download ~/zuliprc-dev from your dev server
client = zulip.Client(config_file="~/zuliprc-dev")

# Unsubscribe from the stream "new stream"
result = client.remove_subscriptions(
    ['new stream']

# Unsubscribe another user from the stream "new stream"
result = client.remove_subscriptions(
    ['new stream'],

More examples and documentation can be found here.

const zulip = require('zulip-js');

// Download zuliprc-dev from your dev server
const config = {
    zuliprc: 'zuliprc-dev',

zulip(config).then((client) => {
    // Unsubscribe from the stream "Denmark"
    const meParams = {
        subscriptions: JSON.stringify(['Denmark']),

    // Unsubscribe Zoe from the stream "Denmark"
    const zoeParams = {
        subscriptions: JSON.stringify(['Denmark']),
        principals: JSON.stringify(['']),


Argument Example Required Description
subscriptions ['Verona', 'Denmark'] Required

A list of stream names to unsubscribe from. This argument is called streams in our Python API.

principals [''] Optional

A list of email addresses of the users that will be unsubscribed from the streams specified in the subscriptions argument. Default is None. If not provided, then the requesting user/bot is unsubscribed.

Return values

  • removed: A list of the names of streams which were unsubscribed from as a result of the query.

  • not_subscribed: A list of the names of streams that the user is already unsubscribed from, and hence doesn't need to be unsubscribed.

Example response

A typical successful JSON response may look like:

    "msg": "",
    "not_subscribed": [],
    "removed": [
        "new stream"
    "result": "success"

A typical failed JSON response for when the target stream does not exist:

    "code": "STREAM_DOES_NOT_EXIST",
    "msg": "Stream 'nonexistent_stream' does not exist",
    "result": "error",
    "stream": "nonexistent_stream"