Subscription Management

This page explains how you can set up subscription management for trigger channels in Lemnisk.

Overview

Digital marketing through various messaging channels such as Email, SMS, WhatsApp, and RCS requires user consent to prevent businesses from over-communication and misuse of these channels. Lemnisk provides a solution for capturing, managing, and updating these subscription consents via a REST API, as well as integrating with the configured channel vendor's webhook callback, wherever available.

The consent (subscribed/unsubscribed) is captured against a specific contact (Phone number/Email) and not a user profile. This ensures the consent is reserved to a particular key, for a specific channel vendor irrespective if your account has configured phone/email as an identifier or not.

What will happen if an engagement is attempted to unsubscribed contacts?

When an engagement is attempted to an unsubscribed key, it will be dropped. UNSUBSCRIBED error will be logged in Campaign Summary failures.

Let's understand how capturing opt-out consents work via the two methods.

Webhook Flow

Webhooks, like delivery reports callback, offered by the different channel vendors, also offer unsubscribe/opt-out webhooks, directly or indirectly.

1. When configuring an existing or new new vendor, if the native integration of that said vendor includes an opt-out/opt-in webhook for the given key (phone number for SMS/Whatsapp/RCS and EmailID for Email), Lemnisk will automatically capture and store the subscription status for that vendor.

2. For eg. Lemnisk's integration with Infobip Whatsapp captures user's unsubcription from the configured handle via infobip's inbound message webhook. Whenever the end-user types "STOP", Lemnisk marks that user (phone number) opt-ed out of the configured Infobip handle.

REST API

Lemnisk offers updating a contact's (phone/email) subscription status using an API call to our Subscription Manager endpoint. Regardless if your account with Lemnisk has phone or email as a user identifier or not, the API can be used to mark the contacts' subscription status in every communication channel.

API Definition

The API only supports POST method.

Endpoint

https://webhooks.lemnisk.co/userSubscriptionManager

Authentication

The following keys are to be applied to Headers of the API request.

api-key required	string	Reach out to your Customer Success Manager to get these keys.
api-passkey required	string

Body Parameter

Parameter Name	Type	Description
action required	String	Expected values - unsubscribed - to mark the provided key as opted-out of the mentioned channel subscribed - to mark the provided key as opted-in for the mentioned channel
channelId required	Integer	Used to define the channel for which the mentioned keys will be subscribed/unsubscribed. SMS - 4 Email - 5 Whatsapp - 27 RCS - 30
values required	Array of strings	Provide the contacts whose subscription status you want to update. Please follow the below format for Phone and Email IDs: Phone numbers: E.164 format Example "[phone]" Email - All lower case. Example "[e-mail]"
vendors required	Array of Integers	Numeric identifier(s) of the channel vendors that you would like to update the subscriptions statuses to. Reach out to your Customer Success Manager to get the VendorIDs to be passed here.

Response Payload

Parameter Name	Description
channel	Name of the channel for which the subscription status was updated. It will be one of - SMS, Email, Whatsapp, RCS
invalid	Array of invalid contacts passed in the request. It will be empty if all keys were correct.
action	Subscription status that was performed in the request - unsubscribed OR subscribed.
vendor	Array of vendor configuration names that have been updated with the subscription status for the provided keys.

Example

Sample Request

curl --location 'https://webhooks.lemnisk.co/userSubscriptionManager' \
--header 'api-key: sample-api-key' \
--header 'api-passkey: sample-api-passkey' \
--header 'Content-Type: application/json' \
--data-raw '{
    "action":"unsubscribed",
    "channelId" : 5,
    "values"  :  ["[phone]","[e-mail]","[e-mail]" ],
    "vendors":  [160]
}'

Response

{
    "channel": "EMAIL",
    "invalid": [
        "[phone]"
    ],
    "action": "unsubscribed",
    "vendors": [
        "Sendgrid_1"
    ]
}

1. The above sample response shows that the first value value passed in the values object (a phone number) in the request is invalid - as a phone number is not the right key for Email channel.

2. The other two emails have been marked unsubscribed. In future, when any email campaign from the above vendor - Sendgrid_1, is attempted where the same two emails are also a part of the audience, UNSUBSCRIBED failure will be registered for that engagement.

List of Errors

Error Response

{
    "error": "Incorrect action passed in request"
}

Error Value	Description
Invalid api-key/api-passkey	Authorisation failure - incorrect api-key or api-passkey in the request.
Incorrect action passed in request	action key in the request contains any other value than subscribed/unsubscribed.
Invalid channel-vendor combination found. No vendorId {{vendorId in request}}, available in channelId {{channelId in request}}.	Either a wrong vendorId or a wrong channelId is passed in the request
{mandatory_key} key not found	A mandatory key in the request is not passed in the request.
The payload length did not match the expected length, payload length should be equal to 4	The payload contains extra and erroneous keys.
length of values Array more than 100 in request	values key contains more than 100 items in the array.