0.1.1 • Public • Published

    OneSignal bulk unsubscribe

    This package can be used to unsubscribe multiple players (users) from your OneSignal app at once based on predefined filters, similar to how Segments work.

    OneSignal currently doesn`t provide any API endpoints for working with Segments nor updating players at once. With onesignal-bulk-unsubscribed you can easily unsubscribe players in one go and specify custom filters.

    Caution! Unsubscribing players is not a destructive job, you can still subscribe them again, but we do NOT provide a way to revert any changes. Use bulk unsubscribe with caution.


    There is an existing onesignal-node (package by zeyneloz)[] but there are two main reasons why this package doesn't use it.

    • onesignal-node doesn't use an Agent for limiting number of open connections, unsubscribing thousands of players at once would simply be too much. This package uses axios with httpsAgent and maxSockets set to 10 to not consume all your computer's sockets.
    • onesignal-node is an API client, so it only gives out CSV URL, this package can download the CSV, including waiting for it being generated, ungzip it and parse it using csvtojson lib.

    How to install

    npm install --save onesignal-bulk-unsubscribe

    How to use

    const bulkUnsubscribe = require('onesignal-bulk-unsubscribe')
      appId: '<APP_ID>', // required
      restApiKey: '<REST_API_KEY>' // required
      filter: <player> => <boolean>,
      mutation: <object> | <player> => <object>,
      timeout: <int>ms,
      backOff: <int>ms,
      dryRun: <boolean>,
      csvFile: <string>,
      csvUrl: <string>,
      parallel: <int>

    appId and restApiKey

    You can find those options in your OneSignal account administration. Keep them secret!


    You should provide a filtering function to filter players you want to unsubscribed. If you do not provide a function, all players will be unsubscribed. There are default filters you can use straight from the package, for example:

    const isInactiveFor30Days = require('onesignal-bulk-unsubscribe/filters').isInactiveFor30Days

    List of available filters:

    • isSubscribed (it might be a good idea to unly unsubscribe players that are subscribed to limit network requests)
    • isInactiveFor90Days
    • isInactiveFor30Days
    • isInactiveFor7Days
    • isInactiveForNDays(days) (this is a closure that returns a filter)

    You can also provide a complex or custom filter, such as

    function filter(player) {
      return isSubscribed(player) && isInactiveFor30Days(player) && player.language !== 'en'


    By default, this package marks all players as unsubscribed (state -1), but you can specify a different mutation to selected players. For example, after trying out this package using a dryRun, you can decide to first mark all players by a tag:

      mutation: {
        tags: {
          toDelete: "true"

    This way, you can verify your filter really works correctly. You can even re-subscribe all players in this way with caution!

    If you wish to modify users based on current properties, a function returning a mutation can be provided:

      mutation: player => {
        if (player.game_version === '1.0') {
          return {
            game_version: '1.1'
        if (player.game_version === '2.0') {
          return {
            game_version: '2.1'
        return {}


    You can specify a timeout in ms for all requests to OneSignal API. Default value is 5000.


    You can specify a backOff time in ms for downloading CSV file. In general, generating a CSV report by OneSignal takes several seconds and provided URL returns 403 status code until the export is generated. By providing a backOff, the package wait for specified number of ms before retrying again. Default value is 10000.


    When testing filters or simply debugging your code, you might wish to not actually unsubscribe any players. You can simply provide dryRun option to only console.log players that would be unsubscribed.

    csvFile and csvUrl

    Those options also serve for debugging and testing. By default, this package first creates a CSV export and then downloads it from OneSignal, doing so multiple times might be wasteful, you can either specify CSV export URL or point to existing CSV file on your drive altogether.


    Specify the limit of maxSockets in https Agent and parallelism of mutations. Default value is 64.


    There is currently no CLI support for this package. Feel free to submit a PR.


    This project is licensed under the terms of the MIT license.



    Feel free to send a PR and we will take a look at it. See package.json and config files for ESLint and Prettier configuration.


    npm i onesignal-bulk-unsubscribe

    DownloadsWeekly Downloads






    Unpacked Size

    14 kB

    Total Files


    Last publish


    • iteconomia