Email unsubscribe

Administrators can add unsubscribe links to notifications so that users can stop receiving particular email messages.

The system offers two types of macros to create unsubscribe links.
  • An unsubscribe link that creates an email message to the instance.
  • An unsubscribe link that opens the notification preferences for the user on the instance.
Table 1. Available unsubscribe macros
Unsubscribe type Macro used Description Available parameters

Unsubscribe by email

(Unauthenticated)

${NOTIF_UNSUB} The system generates an HTML mailto hyperlink. When users click the link, their browser or email client creates a pre-formatted unsubscribe email message to the instance. link_text: specify the text to display as a link within quotation marks.

Unsubscribe by notification preferences

(Authenticated)

${NOTIF_PREFS} The system generates an instance link directly to the notification preferences for this notification type. link_text: specify the text to display as a link within quotation marks.
Administrators can add unsubscribe macros to any notification record type such as:
  • Email layouts
  • Email templates
  • Email notifications

Unsubscribe by email

Unsubscribe by email requires the user email client or browser to create a pre-formatted email message containing these elements:
  • The To field has the email address of the instance.
  • The Subject starts with the string Unsubscribe from.
  • The Body has a JSON string with a name-value pair of Unsubscribe and an array value that contains two more name-value pairs.
    • The notification_id parameter specifies the Sys ID of the notification the user wants to unsubscribe from.
    • The unsub_token parameter specifies an instance ID the system uses to verify that the email came from a ServiceNow instance.
Note: Some email clients and web browsers, such as GMail on Chrome, require extra client configuration to support mailto hyperlinks. Administrators can provide an alternative unsubscribe method for users whose email client or browser does not support mailto links. See RFC6068 for information about the mailto URI scheme.
The Unsubscribe from Notification inbound action processes the email and unsubscribes the sender from the listed notification.
Note: Unsubscribing by email message does not require users to authenticate with the instance first.

Unsubscribe by notification preferences

Unsubscribe by notification preferences requires the user's browser to navigate to the notification preferences page on the instance. After logging in, the system displays the notification preferences for this particular notification.

Users can set preferences for this notification such as disabling notifications for a particular device. Users must save their notification preferences for changes to take effect.

Unsubscribe links

This email layout adds several unsubscribe links to the bottom of each email notification.

${NOTIF_UNSUB} from this notification by email or ${NOTIF_UNSUB+link_text="click
      here"}.
Manage your ${NOTIF_PREFS} or ${NOTIF_PREFS+link_text="click here"}.

When rendered in an email notification, the unsubscribe links only display the link text.

Figure 1. Sample email with unsubscribe links

If a user clicks the Unsubscribe link, the email client creates a message such as this:

Figure 2. Sample unsubscribe by email message