Managing newsletter agreements with API

Upcoming breaking change (effective July 6, 2026): Synerise is introducing changes to how user identifiers and UUIDs are handled. These changes may affect profiles with accented or diacritical characters in identifiers, profiles with leading or trailing whitespace in identifiers, and profiles with duplicate UUIDs. For details and recommended actions, see Upcoming changes to handling identifiers.

Enabling with single/double opt-in

Ensure that a workflow for collecting newsletter agreements is running.

Send a create/update API call with the "newsletter_agreement_enabled": "enabled" attribute.
API reference is available here.

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...G2DI' \
--data-raw '[
   {
      "clientId": 12345,
      "attributes": {
          "newsletter_agreement_enabled": "enabled"
      }
   }
]'

This information is processed in the following way:

The customer's profile is updated with the 'newsletter_agreement_enabled': 'enabled' attribute.
An event with details of the profile update is created and triggers the workflow that collects newsletter agreements.
One of the following happens:
- If single opt-in is used, the agreement is enabled. Depending on the workflow configuration, the customer may receive an email with a notification.
- If double opt-in is used, the customer receives an email and must click the link in that email to confirm the subscription.

Enabling immediately

You can also immediately enable an agreement over the API, without asking for confirmation or notifying the customer.

If you use email address as a unique identifier, send a create/update API call with the agreements.email param set to true.

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...G2DI' \
--data-raw '[
   {
      "clientId": 12345,
      "agreements": {
         "email": true
         }
   }
]'

If you configured non-unique emails, send a create/update API call which changes the attribute you set as the agreement indicator to enabled

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...G2DI' \
--data-raw '[
   {
      "clientId": 12345,
      "attributes": {
         "the-newsletter-agreement-attribute-you-set-up": "enabled"
         }
   }
]'

The agreement is enabled immediately.

API reference is available here.

Disabling a newsletter agreement

If you use email address as a unique identifier, send a create/update API call with the agreements.email param set to false. API reference is available here.

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...G2DI' \
--data-raw '[
   {
      "clientId": 12345,
      "agreements": {
         "email": false
         }
   }
]'

If you configured non-unique emails, send a create/update API call which changes the attribute you set as the agreement indicator to disabled

curl --location --request POST 'https://{SYNERISE_API_BASE_PATH}/v4/clients/batch' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Api-Version: 4.4' \
--header 'Authorization: Bearer eyJ...G2DI' \
--data-raw '[
   {
      "clientId": 12345,
      "attributes": {
         "the-newsletter-agreement-attribute-you-set-up": "disabled"
         }
   }
]'

The agreement is disabled immediately.