> For the complete documentation index, see [llms.txt](https://user.netmera.com/netmera-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://user.netmera.com/netmera-user-guide/customer-data/granular-consent-management.md). # Granular consent management Granular consent management applies user consent per communication purpose and channel, enforced separately. Granular consent management lets you manage user permissions by **communication purpose** and **delivery channel** at the same time. A user can accept promotional emails, reject promotional push notifications, and keep security alerts on every channel — and Netmera enforces each of these decisions separately at send time. In Netmera, communication purposes are represented by **Message Categories**. Each category declares which channels it applies to, and each user holds an independent opt-in state for every **category + channel** pair. The state can be changed by the user (through an in-app preference center built with the Mobile SDK) or by the brand (through the Netmera Dashboard or the REST API, for example from a CRM, a call center, or an unsubscribe flow). For example, you can define: * `promo` — promotional communications * `order_tracking` — order and delivery updates * `security` — account and security notifications {% hint style="info" %} Granular consent management provides the technical structure for purpose- and channel-specific permissions. Your organization remains responsible for determining the consent model, lawful basis, and wording required by applicable regulations. The GDPR references on this page are for orientation and are not legal advice. {% endhint %} ### What's new: channel-based category consent Channel-based category consent removes the single "on / off per category" limitation. It is useful when users want to control not only *what* they receive, but also *where* they receive it. | Capability | Before | Now | | ---------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Category scope | A category applied to every channel | A category is defined for one or more selected channels (Mobile Push, Email, SMS, WhatsApp, In-App, Web Push) | | Consent storage | One state per category | One state per **category + channel** pair | | Opt-out effect | Opting out of a category stopped it on every channel | Opting out of a category on one channel leaves the same category on other channels unchanged | | Default for users without a record | — | Determined per category by the **Subscription Type** (Opt-in or Opt-out) | | User Detail | One toggle per category | One toggle per category and channel | | Targeting | By Category Permission | By Category Permission with a channel selection | | Reporting | Category-level opt-in / opt-out counts | Opt-in / opt-out counts per channel | | REST API and SDK | Category-level read and write | Optional `channel` parameter for category + channel read and write; category-level calls keep working unchanged | Categories created before channel selection was introduced are treated as valid on all channels. No migration is required. ### How consent is evaluated Before delivering a message, Netmera answers three questions. Separating them keeps "where can the user be reached" apart from "why is the message sent" and "does the user accept this purpose on this channel."
CheckQuestion
1. Channel permissionIs the user reachable and permitted on this channel at all (for example, push permission, email permission, SMS permission)?
2. Category + channel preferenceHas the user accepted this communication purpose on this specific channel?
3. Category defaultIf no preference record exists for the category + channel pair, what does the category's Subscription Type say?
A message is delivered only when all applicable checks pass.
General channel permissionCategory + channel preferenceResult
ONON, or no record on an Opt-in categoryDelivered
ONNo record on an Opt-out categoryBlocked until the user opts in
ONOFFBlocked for this category on this channel only
OFFAnyBlocked
For an SMS campaign with the `promo` category, the user must have SMS permission **and** an effective `promo` + SMS permission. The user's `promo` + Email state has no effect on this campaign. {% hint style="info" %} A category-level opt-out never changes the general channel permission. Turning off `promo` on Mobile Push leaves the user's general push permission and all other push categories untouched. If the general channel permission is turned off and later back on, the stored category + channel preferences still apply. {% endhint %} #### Channels and API values The same six channels are available in the panel, the REST API, and the Mobile SDK. | Panel channel | REST API / SDK value | | ------------- | -------------------- | | Mobile Push | `MOBILE` | | Email | `EMAIL` | | SMS | `SMS` | | WhatsApp | `WHATS_APP` | | In-App | `IN_APP` | | Web Push | `WEB` | ### Set up granular consent 1. Define your communication purposes. 2. Create a Message Category for each purpose and select its channels and Subscription Type. 3. Assign the matching category to each campaign. 4. Collect and update category + channel preferences through the SDK, REST API, or Dashboard. 5. Configure İYS when it manages SMS or email consent. 6. Verify preferences, targeting, and campaign eligibility. ### Step 1: Define communication purposes This step turns your communication plan into a small, stable list of purposes. A clear purpose list makes consent requests understandable for users and keeps reporting meaningful for your team. Create one category for each purpose, not one category for each channel. | Purpose | Message Category | Typical channels | | ---------------------------------- | ---------------- | ----------------------- | | Promotional communications | `promo` | Mobile Push, Email, SMS | | Order and delivery updates | `order_tracking` | Mobile Push, Email, SMS | | Account and security notifications | `security` | Mobile Push, Email, SMS | | One-time passwords | `sms_otp` | SMS | Keep Category IDs short, stable, and meaningful. Your integrations and preference center rely on these IDs. ### Step 2: Create Message Categories Categories are where the purpose, its channels, and its default consent behavior are defined. Getting this configuration right determines how every later consent decision is evaluated. In the Netmera Dashboard, select **Settings** → **Messaging & Content** → **Message Categories** and create one category for each purpose. * **Channels:** Select the channels the purpose applies to. At least one channel is required. Only the selected channels accept preference records and appear in campaign category lists. * **Subscription Type:** Choose **Opt-in** (users without a record are subscribed) for purposes users expect by default, such as order tracking. Choose **Opt-out** (users without a record are not subscribed) for purposes that require explicit consent before the first send, such as marketing in regions that require prior consent. * **Category ID:** Immutable after creation. Use a purpose, not a channel. {% hint style="warning" %} Changing the Subscription Type of an existing category clears all stored channel permissions for that category, because the meaning of the stored records is inverted. Decide the Subscription Type before collecting preferences. {% endhint %} Learn more about [Message Categories](/netmera-user-guide/panel-settings/settings/messaging-and-content/message-categories.md).
Message Categories settings page with the option to create a category.

Create a category in Settings

### Step 3: Assign a category to campaigns The campaign category tells Netmera which consent record to check. Without it, purpose-based enforcement cannot be applied to the campaign. Assign the category that matches the message purpose when you create a campaign. The category list in the campaign editor shows only the categories active on the campaign's channel, plus legacy categories. | Message | Channel | Message Category | Consent record checked | | -------------------------- | ----------- | ---------------- | ------------------------ | | New product promotion | Mobile Push | `promo` | `promo` + Mobile Push | | Discount announcement | Email | `promo` | `promo` + Email | | Order shipped notification | SMS | `order_tracking` | `order_tracking` + SMS | | Suspicious login alert | Mobile Push | `security` | `security` + Mobile Push | {% hint style="info" %} Before launching a campaign, verify that its Message Category matches the communication purpose. {% endhint %}
Campaign creation flow with a Message Category selector.

Select a category in the campaign flow

#### Campaign editor examples Each channel uses its own campaign editor, but the category selection serves the same purpose.
Channel-specific campaign editor showing the Message Category selection.

Select the message category in the campaign editor.

Channel-specific campaign editor showing the Message Category selection.

Choose the category that matches the message purpose.

Channel-specific campaign editor showing the Message Category selection.

Confirm the category before completing campaign setup.

### Step 4: Collect and update preferences Category + channel preferences can be written from three sources. This lets the consent state follow the user wherever the decision is made — inside the app, in your backend systems, or by your operations team — while Netmera keeps a single, enforceable record. | Source | Who changes the preference | Typical trigger | | -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Mobile SDK** | The user | In-app preference center or notification settings screen | | **REST API** | The brand, on the user's behalf | CRM or consent-management platform sync, web preference center, email unsubscribe page, SMS keyword reply, call center request | | **Dashboard** | The brand | Manual correction or support request in **User Detail** | Every source updates only the category + channel pair it targets. It does not change the user's general channel permission, the category's other channels, or other categories. #### Mobile SDK The per-channel category preference methods require the following native SDK versions (released September 17, 2026): | Platform | Minimum version | Get preferences | Update preferences | | ----------- | --------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Android | **4.21.0** | `Netmera.getUserCategoryPreferenceList(filter, callback)` with `NMCategoryPreferenceFilter` | `Netmera.setUserCategoryPreference(NMCategoryPreferenceUpdate, callback)` | | iOS (Swift) | **4.26.0** | `Netmera.getUserCategoryPreferenceList(categoryIds:channels:)` | `Netmera.setUserCategoryPreference(categoryId:categoryEnabled:channel:)` | Android example — opt the user out of category `42` on SMS only: ```kotlin val channelPreference = NMCategoryPreferenceUpdate( categoryId = 42, categoryEnabled = false, channel = NMCategoryChannel.SMS ) Netmera.setUserCategoryPreference(channelPreference, object : NMCategoryPreferenceSetCallback { override fun onSuccess() { /* update UI */ } override fun onFailure(error: String?) { /* handle error */ } }) ``` iOS example — read the user's Email and SMS preferences for categories `42` and `43`: ```swift Netmera.getUserCategoryPreferenceList( categoryIds: [42, 43], channels: [.sms, .email] ) { result in // category.categoryEnabled: true if enabled on any channel // category.channelPreferences: per-channel breakdown } ``` * The `channel` argument is optional. Without it, the update applies to every channel of the category, which is the behavior of earlier SDK versions. * The aggregate status (`optInStatus` on Android, `categoryEnabled` on iOS) is `true` when the category is enabled on **any** channel. Use the per-channel breakdown (`channelPreferences`) to render channel toggles. * On Android, `Netmera.setUserCategoryPreference(categoryId, categoryEnabled, listener)` is deprecated and behaves like the new method without a channel. * SDK channel values: `MOBILE`, `SMS`, `EMAIL`, `WHATS_APP`, `IN_APP`, `WEB`. See the Developer Guide for full reference: [Android — Message Categories](https://user.netmera.com/netmera-developer-guide/platforms/android/push-inbox#message-categories) and [iOS — Manage Push Notification Categories](https://user.netmera.com/netmera-developer-guide/platforms/ios/new-ios-swift/push-inbox#manage-push-notification-categories). #### REST API Both category preference endpoints accept an optional channel parameter. When it is omitted, the call behaves exactly as before channel-based preferences were introduced, so existing integrations keep working. | Endpoint | Purpose | Channel parameter | | --------------------------------------- | ----------------------------------------------- | ---------------------------------- | | `POST /rest/3.0/setCategoryPreferences` | Opt a user in or out of a category | `channel` (optional, per entry) | | `GET /rest/3.0/getCategoryPreferences` | Read a user's category preferences | `channels` (optional, list filter) | | `GET /rest/3.0/getPushCategories` | List the categories defined for the application | — | Channel values: `MOBILE`, `SMS`, `EMAIL`, `WHATS_APP`, `IN_APP`, `WEB` (case-insensitive). Opt a user out of `Promotion` on Email only, and out of `Shopping` on every channel: ```bash curl -X POST https://restapi.netmera.com/rest/3.0/setCategoryPreferences \ -H "X-netmera-api-key: your_rest_api_key" \ -H "Content-Type: application/json" \ -d '[ { "extId": "id1", "category": "Promotion", "enable": false, "channel": "EMAIL" }, { "extId": "id1", "category": "Shopping", "enable": false } ]' ``` Read the user's Mobile Push and Email preferences: ```bash curl -G "https://restapi.netmera.com/rest/3.0/getCategoryPreferences" \ -H "X-netmera-api-key: your_rest_api_key" \ --data-urlencode 'externalId=id1' \ --data-urlencode 'channels=MOBILE,EMAIL' ``` ```json { "categoryPreferences": { "Promotion": true }, "categoryChannelPreferences": { "Promotion": { "MOBILE": true, "EMAIL": false } } } ``` * `categoryPreferences` is kept for backward compatibility and is `true` when the user is permitted on any of the category's channels. The `channels` filter does not affect it. * `categoryChannelPreferences` returns the per-channel state. Use it for channel-level decisions. * An entry with an unrecognized `channel` value is skipped and logged; the remaining entries are processed. A typo leaves that preference unchanged instead of updating every channel. See the [Developer Guide — Category Preferences](https://user.netmera.com/netmera-developer-guide/api-documentation/rest-api/user-and-device-management#category-preferences) for all parameters. #### Dashboard Open a user in **User Detail** to see a toggle for each category and channel. Only the channels the category is defined for are editable. A toggle without a stored record reflects the category's Subscription Type. ### Use cases The following scenarios show how channel-based category consent supports common business and compliance requirements. #### 1. In-app preference center A retail app shows a settings screen with a row per category and a toggle per channel. The user keeps **Promotions** on Email, turns it off on Mobile Push and SMS, and keeps **Order Updates** on every channel. * **Implementation:** `getUserCategoryPreferenceList` with `channelPreferences` to render the screen; `setUserCategoryPreference` with `channel` for each toggle. * **Result:** Promotional push and SMS campaigns skip the user; promotional emails and all order updates are still delivered. * **GDPR reference:** Art. 7(3) — withdrawing consent must be as easy as giving it. Recital 43 — separate consent for different processing operations. #### 2. Channel-specific unsubscribe from an email or SMS A user clicks the unsubscribe link in a promotional email, or replies with an opt-out keyword to a promotional SMS. The user objects to that message type on that channel, not to all communication. * **Implementation:** Your unsubscribe page or SMS keyword handler calls `setCategoryPreferences` with `"channel": "EMAIL"` or `"channel": "SMS"` and `"enable": false`. * **Result:** Only `promo` + Email (or `promo` + SMS) is turned off. Promotional push, order tracking, and security messages continue as consented. * **GDPR reference:** Art. 21(2)–(3) — right to object to direct marketing at any time; once exercised, the data must no longer be processed for that purpose. Art. 7(3) — withdrawal of consent. #### 3. Consent collected in another system (CRM, CMP, web, call center) Consent is captured outside the app — during web registration, in a consent-management platform, or by a call center agent — and Netmera must reflect it. * **Implementation:** Your backend syncs changes with `setCategoryPreferences`, sending one entry per category + channel pair. Use `getCategoryPreferences` to reconcile states. * **Result:** Netmera enforces the same decision the user gave elsewhere, without waiting for an app session. * **GDPR reference:** Art. 7(1) — the controller must be able to demonstrate consent; keeping one enforceable record per purpose and channel supports this. Art. 5(1)(d) — accuracy. #### 4. Explicit consent before the first marketing message Some markets or internal policies require that no marketing message is sent until the user explicitly agrees. * **Implementation:** Create the marketing category with Subscription Type **Opt-out**. Users without a record are not subscribed. Write an opt-in record only after the user agrees on a given channel. * **Result:** New users receive no marketing on any channel until they opt in on that channel. * **GDPR reference:** Art. 4(11) and Art. 6(1)(a) — consent must be a clear affirmative act. Art. 25(2) — data protection by default. ePrivacy Directive Art. 13 — prior consent for electronic direct marketing. #### 5. Keeping service messages separate from marketing A user opts out of every promotional channel but must still receive order and security notifications. * **Implementation:** Keep `order_tracking` and `security` as separate categories from `promo`, and assign them to their campaigns. * **Result:** A marketing opt-out never blocks service messages, and service channels cannot be reused for promotional content without a visible category mismatch. * **GDPR reference:** Art. 5(1)(b) — purpose limitation. Art. 7(2) — a consent request must be clearly distinguishable from other matters. Recital 32 — consent should cover all purposes; when processing has multiple purposes, consent should be given for each of them. #### 6. Purpose-limited SMS categories An OTP category is defined for SMS only. * **Implementation:** Create `sms_otp` with only SMS selected. It does not appear in other channels' campaign editors, and no preference records can be created for it on other channels. * **Result:** The purpose is restricted to the channel it was collected for. * **GDPR reference:** Art. 5(1)(b) — purpose limitation; Art. 5(1)(c) — data minimisation. ### GDPR reference summary | Article | Principle | How granular consent management supports it | | -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Art. 4(11) | Consent is specific, informed, and unambiguous | Each category + channel pair is a separate, specific decision | | Art. 5(1)(b) | Purpose limitation | Categories represent purposes; campaigns must declare one | | Art. 5(1)(c) | Data minimisation | Categories can be restricted to the channels the purpose needs | | Art. 5(1)(d) | Accuracy | REST and SDK keep the Netmera record aligned with decisions made in other systems | | Art. 6(1)(a) | Consent as a lawful basis | Opt-out Subscription Type prevents sending before an explicit opt-in | | Art. 7(1) | Ability to demonstrate consent | Per-channel states are visible in User Detail and retrievable through `getCategoryPreferences` | | Art. 7(2) | Consent request clearly distinguishable | Separate categories for marketing and service messages | | Art. 7(3) | Withdrawal as easy as giving consent | One toggle or one API call withdraws consent for a single purpose on a single channel | | Art. 21(2)–(3) | Right to object to direct marketing | A marketing opt-out on a channel is enforced on the next send | | Art. 25(2) | Data protection by default | Opt-out Subscription Type defaults new users to not subscribed | | Recital 32, 43 | Consent per purpose; separate consent for separate operations | Consent is stored per category and per channel | {% hint style="warning" %} In Türkiye, commercial electronic messages over SMS, email, and calls are also subject to İYS. İYS consent and Message Category preferences manage different permissions; configure both. See Step 5. {% endhint %} ### Common implementation pattern ``` Communication purpose ↓ Message Category (with channels and Subscription Type) ↓ User preference per category + channel (SDK, REST API, Dashboard) ↓ Campaign category and campaign channel ↓ Channel permission + category/channel permission ↓ Message delivery ``` For a promotional email campaign: ``` Promotion ↓ promo (Mobile Push, Email, SMS) ↓ User: promo + Email = ON, promo + Mobile Push = OFF ↓ Email campaign uses promo ↓ User has email permission ↓ Eligible for delivery (a push campaign with promo would be blocked) ``` ### Recommended category structure Don't create separate categories for the same purpose: * `push_promo` * `sms_promo` * `email_promo` Use a single `promo` category and select the channels it applies to. Channel-level consent is stored under that single category, so users and reports see one purpose with a per-channel breakdown. Use `order_tracking`, `security`, and `account_updates` for separate purposes. This keeps category management maintainable as you add channels. ### Step 5: Configure İYS when applicable If İYS manages SMS or email consent, decide which system owns consent records before configuring the integration. #### İYS integrator mode Netmera collects consent information and sends relevant updates to İYS. #### İYS sync mode Netmera retrieves consent information from İYS. İYS remains the consent record source. Choose the mode that matches your consent-management process. * [İYS Permissions](/netmera-user-guide/customer-data/iys-permissions.md) * [İYS Sync Mode](/netmera-user-guide/customer-data/iys-permissions/iys-sync-mode.md) * [İYS Integrator Mode](/netmera-user-guide/customer-data/iys-permissions/iys-integrator-mode.md) {% hint style="warning" %} İYS consent management and Message Categories manage different communication permissions. Configure both for your consent and governance model. {% endhint %} ### Step 6: Verify preferences and eligibility Verification confirms that the consent recorded for a user produces the delivery result you expect, before a campaign reaches production. #### Check User Details Open [People](/netmera-user-guide/targeting/people.md) and review the user's per-channel category toggles. #### Check targeting Under **Targeting** → **Find People**, use **By Category Permission** with a channel selection to count users with a given category + channel state. With no channel selected, the condition evaluates the campaign's channel or, with no campaign context, the category's own channels. #### Check Channel Reachability Use [Channel Reachability](/netmera-user-guide/reports-and-analytics/reports/audience-and-growth/channel-reachability.md) to review permission coverage by purpose and channel. The Message Categories list shows opt-in and opt-out counts per channel; there is no single category-level figure, because a user can hold a different state on each channel. #### Test scenarios For a new category, test at least the following with a test user: | Scenario | Expected result | | -------------------------------------------------------- | ------------------------------------------------------------------ | | Channel permission ON, category + channel ON | Delivered | | Channel permission ON, category OFF on this channel only | Blocked on this channel; same category on other channels delivered | | Channel permission ON, no record, Opt-in category | Delivered | | Channel permission ON, no record, Opt-out category | Blocked | | Channel permission OFF, category + channel ON | Blocked |
Channel Reachability report showing permission data by messaging channel.

Review permission coverage by channel.

Message category report with opt-in and opt-out user counts.

Opt-in and opt-out users by message category

### Related pages * [Message Categories](/netmera-user-guide/panel-settings/settings/messaging-and-content/message-categories.md) * [İYS Permissions](/netmera-user-guide/customer-data/iys-permissions.md) * [İYS Sync Mode](/netmera-user-guide/customer-data/iys-permissions/iys-sync-mode.md) * [İYS Integrator Mode](/netmera-user-guide/customer-data/iys-permissions/iys-integrator-mode.md) * [Contact Upload](/netmera-user-guide/targeting/contact-upload.md) * [Channel Reachability](/netmera-user-guide/reports-and-analytics/reports/audience-and-growth/channel-reachability.md) * [People](/netmera-user-guide/targeting/people.md) * [Opt-out](/netmera-user-guide/reports-and-analytics/analytics/user-and-audience/opt-out.md) * [Developer Guide — REST API Category Preferences](https://user.netmera.com/netmera-developer-guide/api-documentation/rest-api/user-and-device-management#category-preferences) * [Developer Guide — Android Message Categories](https://user.netmera.com/netmera-developer-guide/platforms/android/push-inbox#message-categories) * [Developer Guide — iOS Message Categories](https://user.netmera.com/netmera-developer-guide/platforms/ios/new-ios-swift/push-inbox#manage-push-notification-categories) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://user.netmera.com/netmera-user-guide/customer-data/granular-consent-management.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.