Setup Newsletter – Unidy Documentation

This article provides all relevant information you need to setup newsletter subscriptions and respective preferences in Unidy.

1. Architecture of Newsletters in Unidy

Unidy allows you to create an unlimited number of newsletter subscriptions, giving customers the freedom to subscribe to as many newsletters as they like. This flexibility supports personalized engagement across diverse interests and marketing campaigns.

When a customer subscribes to a newsletter, a unique subscription is created. Each subscription is specifically linked to:

One Email Address: Subscriptions are tied to individual email addresses for accurate and efficient management.

One Newsletter: Each subscription is associated with a single newsletter.

Importantly, the email address used for a subscription does not need to be linked to a registered user account. This optional account association enables broader audience reach and simpler participation.

1.1. Attributes of the Newsletter Object

{
  "id": 405,
  "email": "tm@unidy.de",
  "confirmed_at": null,
  "opted_out_at": null,
  "newsletter_id": 2,
  "preference_token": "qeCotyLGYBFvHNYgjHvKgLFz",
  "user_id": "67fb6469-dd79-400f-b92b-532520ac4e9c",
  "preference_identifiers": []
}

Name	Type	Description
id	Number	Ascending number for each newsletter subscription in your Unidy account.
email	String	Subscribers email address
confirmed_at	Timestamp	Time and date that the subscriber confirmed the newsletter subscription
opted_out_at	Timestamp	Time and date that the subscriber unsubscribes from the newsletter.
newsletter_id	Number	ID of the newsletter that the subscriber subscribed to. For each newsletter subscription, a new row will be added (→ the combination of newsletter_id and email is unique).
preference_token	String	Unique token that can be used in URLs to let subscribers manage their newsletter preferences without being logged in. See link on information how to use this.
user_id	String	If the email that is used for subscribing to the newsletter already belongs to a user account, the user_id (Unidy ID) will link to the respective user account. This is optional and will be NULL otherwise.
preference_identifiers	Array	Internal names of the corresponding newsletter preferences, that user is interested in.

Each newsletter can have preference groups which themselves can contain preferences

When creating a newsletter, certain attributes are stored together with it.

1.2. Preferences and Preference Groups

Preferences allow customers to express their areas of interest, helping tailor content to their needs. However, selecting preferences does not constitute a legal opt-in. The actual opt-in remains tied to the specific newsletter, while preferences simply reflect user interests within that context.

To organize these interests effectively, preferences are grouped into Preference Groups, which enhance personalization in a structured way. Key aspects of this system include:

Each preference belongs to one preference group.

Each preference group is associated with a single newsletter.

Newsletters can exist without a preference group.

Preference groups can be created without any preferences, but they will only be visible to users when at least one preference is assigned.

This structure supports both flexibility and clarity, enabling more personalized communication without complicating the subscription process.

1.3. Preference Token

A Preference Token is a unique identifier used within Unidy to manage and track a customer’s newsletter subscription preferences. It is an alphanumeric string—typically in a format such as K1RL8fxpauvxrNUqHG9Kkmii generated to ensure both uniqueness and security.

This token enables precise identification and efficient association of preferences with the corresponding subscriber, supporting seamless personalization and subscription management.

Use Cases for Preference Tokens

Direct Preference Management via Token Link

Embed the unique Preference Token in the URL https://brand.unidy.de/newsletter?token=*Exemplarytoken* and include it in your newsletters. Clicking on the url recipients can access their personalized newsletter management page directly, where they can view and manage their subscriptions and preferences.

External System Integration

The Preference Token also functions as a unique identifier for newsletter subscriptions across external systems. It facilitates smooth integration by linking the preferences managed in Unidy to third-party platforms. The token is included in the subscription payload and can be transmitted effortlessly through API or webhook connections, ensuring consistent and accurate data exchange.

1.4. Newsletter Structure

Name	Options	Description
NEWSLETTER
Internal name	Text	This name will be used to identifying newsletters in the connected systems. Please type in a meaningful, short and self-explanatory name in English. This field only supports the snake case.
Title	Text
Description	Text
Default	True/False	Default newsletters will be subscribed to during registration when using checkbox to ask for your customer’s consent.
Visible for brand	True/False for each available brand	Determines on which brands the newsletter will be available.
Opt in type	`doi` , `soi` or `soi_when_logged_in`	Decide whether the newsletter always needs a double opt in confirmation `doi`. With the single opt in setting `soi` , the subscription is always confirmed and no DOI email is sent. With the setting `soi_when_logged_in` a DOI email is only sent when the user is not logged in at Unidy while subscribing.
Doi through unidy	True/False	When activated, Unidy will send out the DOI email. The template can be customized by you Customer Success Manager.

1.5. Preference Structure

Name	Options	Description
PREFERENCE
Name	Text
Description	Text
Plugin identifier	Text	This will be used to identifying preferences in the connected systems. Please type in a meaningful, short and self-explanatory name in English. This field only supports the snake case.
Default	True/False	Default preference are automatically enabled when subscribing to a newsletter without specifying preferences. When no preference is configured as default, all will be enabled.
Hidden	True/False	You can also hide preferences in case you don’t want them to be visible for your customers.
Position	Number	Defines at which position the preference will be displayed to your customers. Can be left empty.

2. Setup Guides

2.1. Set up a new newsletter

Navigate to admin > settings > newsletter and click on new.

Add information as described in 1.4. and click create newsletter when done.

Remember to update sync to external systems if you have newsletter sync configured anywhere!

❗

You can add translations for all visible texts (please refer to Languages & Translations – Unidy Documentation)

2.2. Set up preferences

If you want to use preferences for your newsletters:

Click on respective newsletter you want to add preferences for.

Scroll to Preference Groups and click New.

You can order multiple groups after creating them by dragging and dropping.

Enter name and select flat if you display preference directly on newsletter and not in accordion, then click Add.

Scroll down to preferences and click New.

Fill out information and click save.

Regarding the position: The position will be relative to the other preferences within the same group. You can also leave this blank and order them later by dragging and dropping them after saving

Repeat to add as many preferences as you like.

2.3. Edit newsletters

⚠️

Deleting a newsletter subscription will update the preferences of all associated newsletter subscriptions!

Select newsletter you want to update.

Click edit or delete for preference groups / preferences.

The HubSpot plugin will automatically update the respective HubSpot preferences accordingly.