Skip to main content

​
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. 
import suprsend

supr_client = suprsend.Suprsend("workspace_key", "workspace_secret")

distinct_id = "distinct_id"  # Unique identifier of user in your application

# Instantiate User profile
user = supr_client.users.get_edit_instance(distinct_id)

​
Edit User

To Edit user, you need to first fetch user instance, call all the update methods and save changes using users.async_edit method. 
#Fetch user instance
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
res = supr_client.users.async_edit(user)
print(res)
Here’s a list of all edit methods:
Add communication channels on which you want to notify user. Push sand Inbox tokens are automatically tracked on user identification when the corresponding frontend SDK is integrated. Other channels (Email, SMS, Slack, MS teams, WhatsApp) need to be explicitly set in user profile.Use user.add_* method(s) to add user channels.
# Add channel details to user-instance. Call relevant add_* methods

user.add_email("user@example.com") # - To add Email

user.add_sms("+15555555555") # - To add SMS

user.add_whatsapp("+15555555555") # - To add WhatsApp

user.add_androidpush("__android_push_fcm_token__")

user.add_iospush("__iospush_token__")

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

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

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

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

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

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

# - To add MS teams using incoming webhook
user.add_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })
Use user.remove_* method(s) to remove channels.
# Remove channel details from user-instance. Call relevant remove_* methods

user.remove_email("user@example.com")

user.remove_sms("+15555555555")

user.remove_whatsapp("+15555555555")

user.remove_androidpush("__android_push_fcm_token__")

user.remove_iospush("__iospush_token__")

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

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

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

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

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

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

# - To remove MS teams using incoming webhook
user.remove_ms_teams(
  {
    "incoming_webhook": {
      "url": "https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX"
    }
  })
This method will delete/unset all values in specified channel for user (ex: remove all emails attached to user).
# --- To delete all emails associated with user
user.unset("$email")
user.unset(["$email", "$sms", "$whatsapp"])

# Supported channel keys are:
# $email, $whatsapp, $sms, $androidpush, $iospush, $webpush, $slack, $ms_teams
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")
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 is used to add custom user properties. It is an upsert function, meaning any existing property value with the same key will be overwritten on subsequent updates.
user.set(key, value)
user.set("name","John Doe")

user.set({ key1: value1, key2: value2 })
user.set({"name": "John Doe","city": "San Francisco"})
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"})
Unset is used to remove a property key.
user.unset(key)
user.unset("name")

user.unset([key1, key2])
user.unset(["name","city"])
This method will append a value to the array list.
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"})
This method will remove a value from the array list.
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"})
Increase or decrease integer values on consecutive action, like login count. 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})
After calling add*/remove*/unset methods, don’t forget to call users.async_edit() since user edit is async update and the changes will be sent to SuprSend only after calling this method.

​
Bulk 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. 
# Create bulk instance
bulk_ins = supr_client.users.get_bulk_edit_instance()

# Prepare multiple users edit instance
distinct_id1 = "__distinct_id1__"  # User 1
u1 = supr_client.users.get_edit_instance(distinct_id1)
u1.add_email("u1@example.com")

distinct_id2 = "__distinct_id2__"  # User 2
u2 = supr_client.users.get_edit_instance(distinct_id2)
u2.add_email("u2@example.com")

# Append users to the bulk instance
bulk_ins.append(u1, u2)

# -------
res = bulk_ins.save()
print(res)
Bulk API supported in SDK version 0.2.0 and above:Bulk API is supported in SuprSend python-sdk version 0.2.0 and above. If you are using an older version, please upgrade to the latest SDK version.

​
Get user details

res = supr_client.users.get("_distinct_id_")
print(res)

​
Delete user

res = supr_client.users.delete("_distinct_id_")
print(res)

​
Get list of objects subscribed by user

You can pass optional query parameters -limit, before, after 
res = supr_client.users.get_objects_subscribed_to("_distinct_id_", {"after": "01JJW6HXXXXPB59ARDW85G0KN", "limit": 1})
print(res)

​
Get lists subscribed by user

You can pass optional query parameters -limit, before, after 
res = supr_client.users. get_lists_subscribed_to("_distinct_id_", {"after": "01JJW6HXXXXPB59ARDW85G0KN", "limit": 1})
print(res)
⌘I