Manage Users

How SuprSend identifies a User

SuprSend identifies users with immutable distinct_id. It’s best to map the same identifier in your DB with distinct_id in SuprSend. Do not use identifiers that can be changed like email or phone number. You can view synced users by searching distinct_id on Users page.

Create User

To create a new user or to update an existing user, you’ll have to fetch user instance. Call supr_client.user.get_instance to instantiate user object.

const user = supr_client.user.get_instance("_distinct_id_"); // create user instance

// user methods mentioned in this docs can be attached to user instance if needed

const response = user.save() // IMP: trigger request
response.then((res) => console.log("response", res));

{
  "success": boolean,
  "status": "success"/"fail",
  "status_code": http_status_code,
  "message": "response_message"/"error_message",
}

Edit User

To Edit user, you need to first fetch user instance, call all the update methods and save changes using user.save() method.

// Fetch user instance
const user = supr_client.users.get_edit_instance("_distinct_id_");

// Call user update methods
user.set_timezone("America/Los_Angeles");
user.set("name", "John Doe");

// Save Changes
const response = user.save(); // IMP: trigger request
response.then((res) => console.log("response", res));

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "User updated successfully"
}

Here’s a list of all edit methods:

Add User Channels

Use user.add_* method to add user channels.

// add Email
user.add_email("user@example.com")

// add SMS
user.add_sms("+15555555555")

// add Whatsapp
user.add_whatsapp("+15555555555")

// add fcm push token
user.add_androidpush("__android_push_fcm_token__")

// add apns push token
user.add_iospush("__iospush_token__")

// add Slack using email
user.add_slack({
  email: "user@example.com",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack if slack member_id is known
user.add_slack({
  user_id: "U03XXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack channel
user.add_slack({
  channel_id: "CXXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// add Slack incoming webhook
user.add_slack({
  incoming_webhook: {
    url: "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
  }
});

// add MS teams user or channel using conversation_id
user.add_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  conversation_id: "19:c1524d7c-a06f-456f-8abe-xxxx"
});

// add MS teams user using user_id
user.add_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  user_id: "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
});

// add MS teams using incoming webhook
user.add_ms_teams({
  incoming_webhook: {
    url: "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
  }
});

Remove User Channels

Use user.remove_* method(s) to remove user channels. These methods will detach provided value from the user profile in specified channel.

// remove Email
user.remove_email("user@example.com")

// remove SMS
user.remove_sms("+15555555555")

// remove Whatsapp
user.remove_whatsapp("+15555555555")

// remove fcm push token
user.remove_androidpush("__android_push_fcm_token__")

// remove apns push token
user.remove_iospush("__iospush_token__")

// remove Slack email
user.remove_slack({
  email: "user@example.com",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack if slack member_id is known
user.remove_slack({
  user_id: "U03XXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack channel
user.remove_slack({
  channel_id: "CXXXXXXXX",
  access_token: "xoxb-XXXXXXXX"
});

// remove Slack incoming webhook
user.remove_slack({
  incoming_webhook: {
    url: "https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX"
  }
});

// remove MS teams user or channel using conversation_id
user.remove_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  conversation_id: "19:c1524d7c-a06f-456f-8abe-xxxx"
});

// remove MS teams user using user_id
user.remove_ms_teams({
  tenant_id: "c19xxxx2-9aaf-xxxx-xxxx",
  service_url: "https://smba.trafficmanager.net/amer",
  user_id: "29:1nsLcmJ2RKtYH6Cxxxx-xxxx"
});

// remove MS teams using incoming webhook
user.remove_ms_teams({
  incoming_webhook: {
    url: "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
  }
});

Remove User Channels in bulk

This method will delete/unset all values in specified channel for user (ex: remove all emails attached to user).

user.unset("$email")
user.unset(["$email", "$sms", "$whatsapp"])

// what value to pass to unset channels
// for email:                $email
// for whatsapp:             $whatsapp
// for SMS:                  $sms
// for androidpush tokens:   $androidpush
// for iospush tokens:       $iospush
// for webpush tokens:       $webpush
// for slack:                $slack
// for ms_teams:             $ms_teams

Set Preferred Language

If you want to send notification in user’s preferred language, you can set it by passing language code in this method. This is useful especially for the applications which offer vernacular or multi-lingual support.

user.set_preferred_language("en")

Set Preferred Timezone

You can set timezone of user using this method. Value for timezone must be from amongst the IANA timezones.

user.set_timezone("America/Los_Angeles")

Set

Set is used to set the custom user property or properties. The given key and value will be assigned to the user, overwriting an existing property with the same key if present.

user.set(key, value)
user.set("name","John Doe")

user.set({ key1: value1, key2: value2 })
user.set({"name": "John Doe","city": "San Francisco"})

Parameters	type
key	string
value	any

Set Once

Works just like user.set, except it will not override already existing property values. This is useful for properties like first_login_date.

user.set_once(key, value)
user.set_once("first_login","2021-11-02")

user.set_once({ key1: value1, key2: value2 })
user.set_once({"first_login": "2021-11-02","signup_date": "2021-11-02"})

Append

This method will append a value to the list for a given property.

user.append(key, value)
user.append("played_games", "game_1")

user.append({ key1: value1, key2: value2 })
user.append({"played_games": "game_1", "liked_games": "game_2"})

Remove

This method will remove a value from the list for a given property.

user.remove(key, value)
user.remove("played_games", "game_1")

user.remove({ key1: value1, key2: value2 })
user.remove({"played_games": "game_1", "liked_games": "game_2"})

Increment

Add the given number to an existing property on the user. If the user does not already have the associated property, the amount will be added to zero. To reduce a property, provide a negative number for the value.

user.increment(key, value)
user.increment("login_count", 1)

user.increment({ key1: value1, key2: value2 })
user.increment({"login_count" : 1, "order_count" : 1})

Parameters	type
key	string
value	number (+ or -)

Unset

This will remove a property permanently from user properties.

user.unset(key)
user.unset("wishlist")

user.unset([key1, key2])
user.unset(["wishlist", "cart"])

Parameters	type
keys	string

After calling add*/remove*/unset methods, don’t forget to call the user.save() request. the changes will be sent to SuprSend only after calling this method.

Bulk Update Users

Bulk operations use UPSERT to create or update users. There isn’t any limit on number-of-records that can be added to bulk_users instance. Use .append() on bulk_users instance to add however-many-records to call in bulk.

Rate limit: 1000 requests per second. The SDK automatically chunks requests based on the size of the payload. So, you don’t need to worry about these rate limits while using bulk operations.

const { Suprsend } = require("@suprsend/node-sdk");

const supr_client = new Suprsend("workspace_key", "workspace_secret");

const bulk_ins = supr_client.bulk_users.new_instance()

// user1 instance
const user1 = supr_client.user.get_instance("_distinct_id_1")
user1.add_email("u1@example.com")
user1.set_preferred_language("en")

// user2 instance
const user2 = supr_client.user.get_instance("_distinct_id_2")
user2.remove_email("u2@example.com")

//append users instance to bulk instance
bulk_ins.append(user1)
bulk_ins.append(user2)
// OR
bulk_ins.append(user1, user2)

 // trigger request
const response = bulk_ins.save()
response.then((res) => console.log("response", res));

{
  status: "success/fail/partial",
  total: 10,
  success: 10,
  failure: 0,
  failed_records: [{"record": {...}, "error": "error_str", "code": "<status_code>"}],
  warnings: []
}

Get user details

const response = await supr_client.users.get(_distinct_id_);

Delete user

const response = await supr_client.users.delete(_distinct_id_);

Get list of objects subscribed by user

const response = await supr_client.users.get_objects_subscribed_to(_distinct_id_, {limit:20});

You can pass optional query parameters - limit,before,after.

Get lists subscribed by user

const response = await supr_client.users.get_lists_subscribed_to(_distinct_id_, {limit:20});

You can pass optional query parameters - limit,before,after.

Developer Resources

Updates and Versioning

Authentication

Security

SDKs and APIs

Features

Testing

Monitoring and Logging

How SuprSend identifies a User

Create User

Edit User

Bulk Update Users

Get user details

Delete user

Get list of objects subscribed by user

Get lists subscribed by user

​How SuprSend identifies a User

​Create User

​Edit User

​Bulk Update Users

​Get user details

​Delete user

​Get list of objects subscribed by user

​Get lists subscribed by user

How SuprSend identifies a User

Create User

Edit User

Bulk Update Users

Get user details

Delete user

Get list of objects subscribed by user

Get lists subscribed by user