Home

Integrations

Interactive bots (beta)

REST API

Messages

Streams

Users

Server & organizations

Real-time events

Specialty endpoints

Back to Zulip

Remove subscriptions

Unsubscribe yourself or other users from one or more streams.

DELETE https://chat.zymocosm.com/api/v1/users/me/subscriptions

Usage examples

  • Python
  • JavaScript
  • curl

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

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

# Unsubscribe another user from the stream "new stream"
result = client.remove_subscriptions(
    ['new stream'],
    principals=['newbie@zulip.com']
)
print(result)

More examples and documentation can be found here.

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

// Pass the path to your zuliprc file here.
const config = {
    zuliprc: 'zuliprc',
};

zulip(config).then((client) => {
    // Unsubscribe from the stream "Denmark"
    const meParams = {
        subscriptions: JSON.stringify(['Denmark']),
    };
    client.users.me.subscriptions.remove(meParams).then(console.log);

    // Unsubscribe Zoe from the stream "Denmark"
    const zoeParams = {
        subscriptions: JSON.stringify(['Denmark']),
        principals: JSON.stringify(['ZOE@zulip.org']),
    };
    client.users.me.subscriptions.remove(zoeParams).then(console.log);
});


curl -sSX DELETE https://chat.zymocosm.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode subscriptions='["Verona", "Denmark"]'

You may specify the principals argument like so:

curl -sSX DELETE https://chat.zymocosm.com/api/v1/users/me/subscriptions \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode subscriptions='["Verona", "Denmark"]' \
    --data-urlencode principals='["ZOE@zulip.com"]'

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

Arguments

Argument Example Required Description
subscriptions ["Verona","Denmark"] Yes

A list of stream names to unsubscribe from. This argument is called streams in our Python API.
principals ["ZOE@zulip.com"] No

A list of email addresses of the users that will be unsubscribed from the streams specified in the subscriptions argument. 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_removed: 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_removed": [],
    "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"
}