Our business value:

Customer Identity Management
Profile Management
RaaS



Gigya Job Openings

Email Templates

Skip to end of metadata
Go to start of metadata

 

Email Templates

Use the Email Templates page in the Console to design the emails that are sent out to users as part of their site journey. The SAP Customer Data Cloud email templates are fully customizable.
Note that separate email templates are used when implementing Comments; these templates can be modified in the Comments settings.

Templates can be added in multiple languages. You can access the Email Templates page under Registration-as-a-Sevice:

Note: When using site groups, Child sites automatically inherit email templates from their master site. To override email templates per child site, select Override master settings.

Watch an Instructional Video

If you have an SAP logon, you can watch an instructional video about email templates here.

Setting Email Content

The Email Templates page has a tab for each type of email template:

The Email Templates are displayed in a table and templates can be added by clicking the Add Template button on the right. If there are multiple templates, a default template must be selected. The default language is English, you can select a different language when you define a new template. Email templates are setup as an HTML template with placeholders and META tags. The placeholders are variables that are replaced with actual values when the email is sent. The META tags define the header of the email.
You can preview an email template by clicking the preview icon on the right side next to the template.

 

META Tags

All email templates support meta tags. The META tags define the header of the email. The supported META tags:

  • <META name="from" content="Name <noreply@YOUR-SITE.com" />

    • Specifies the alias/reply address of the email, i.e., what will be written in the "from" field of the email and where replies are directed to when someone clicks 'Reply'.

      The default sender for all emails is 'noreply@gigya-raas.com', they are sent out from a 'gigya-raas' domain. To send emails from your own mail server, see Sending an Email From Your Domain.

  • <META name="subject" content="Account Activation" /> 
    • Defines the subject of the email.

 

Placeholders

All templates support the following placeholders. In addition, individual screens may support additional placeholders:

  • $firstName - The user's first name *
  • $lastName - The user's last name *
  • $nickname - The user's nickname *
  • $username - The user's name as defined in the loginIDs.username field in the Account object *
  • $name - The user's name *
  • $birthDay - The day on which the user was born
  • $birthMonth - The month in which the user was born
  • $birthYear - The year in which the user was born
  • $age - The user's age
  • $UID - The user's UID
  • $email - The user's email address (not supported for DOI emails, Double Opt-In email templates must use $profile.email)
  • $gender - The user's gender
  • $city - The user's city *
  • $state - The user's state *
  • $zip - The user's postal code *
  • $country - The user's country *
  • $photoURL - A url pointing to the user's profile photo
  • $thumbnailURL - A url pointing to a thumbnail of the user's profile photo
  • $profileURL - A url pointing to the user's profile

* Limited to a maximum of 30 characters. Also, if these fields contain a period, it will be replaced by a Unicode character that is visually similar to a period, to prevent the field from being clickable. 

Adding Localized Templates 

Some templates come with a predefined default English template (see the screen-shot above). In addition to editing the default English template, you may add more templates for other languages.
Click Add Template. Then select the language, and edit the content of the template. When you finish click the "Save Settings" button. The list of supported languages and their codes can be found in our Language Support guide.
SAP Customer Data Cloud determines which language email template to use when sending a verification email according to the profile.locale on the user's account.
For example, a user will receive a verification email in Spanish if:
  1. The site has a template for Spanish, with language "ES".
  2. A user registers and sets their profile.locale field to "ES" (or the site sets it for them in the registration process).
  3. The user goes through the email verification flow.

Note: If a user does not have a value for the profile.locale field then the default English ("EN") template email is sent (e.g., if someone registers via Twitter to a site that has Email Verification enabled).

 

 

Password Reset

Setting up the reset password flow includes defining the template of the reset password email received by the user, and the landing page to which the user is redirected when clicking the reset password link. 

Password Reset Landing Page

If you are using SAP Customer Data Cloud's screen-sets, there should be a page on your site that hosts the Reset Password screen. This page should call accounts.showScreenSet with the name of your Reset Password screen. 

<script src="https://cdns.gigya.com/js/gigya.js?apikey=<Your-API-Key>" type="text/javascript"></script>
 
gigya.accounts.showScreenSet({
    screenSet: 'documentation-0001-RegistrationLogin',
    startScreen:'gigya-reset-password-screen',
});

 

Then, you should enter that URL under Reset Page URL in the Password Reset Email Template settings in the Email Templates page of the Console. 

This URL must be publicly accessible; e.g., can not be behind a firewall or HTTP Auth.

 

Note that you can structure the reset page URL dynamically, using the following placeholders for the site API key, and the reset password token. If not specified, these parameters will be added automatically to the URL as they are today. Using the placeholders can be easier for routing in the case of single-page apps and you need these values located inside uniquely named variables, or in case the URL contains a # fragment: 

  • {apiKey} - the site API key 
  • {pwrt} - the password reset token

Example URL structure: 

 https://mysite.com/#creds={pwrt}_{apiKey}



After a user successfully resets their password, they will be presented with the Reset Password Success screen. You may customize this screen to open the Login screen or redirect the user to another page.

Like all SAP Customer Data Cloud's screens, the Reset Password and Reset Password Success screens can be customized using the UI Builder. 

Defining a Reset Page When Not Using Screen-Sets

If you are not using screen-sets, you should set up a URL of a page where the password can be reset. The user will receive an email that includes a reset link, which leads to the URL specified here. SAP Customer Data Cloud provides a default reset password page which is located at: https://<your CNAME>/newPassword (or https://socialize.gigya.com/newPassword if CNAME is not specified for your site). You can set up a different URL for your reset password page. 

The reset link in the email also includes a token as a URL parameter, the format is: <reset page URL> ?pwrt=<reset token> 

The token is used to verify the authenticity of the user and their ownership of the account.

 

Password Reset Email

Password reset emails are sent whenever a user chooses to reset their password. The password reset email is valid for 1 hour by default. You can change that definition using the passwordReset.tokenExpiration parameter of accounts.setPolicies. In addition to the placeholders listed above, you can use the following placeholders:
  • $pwResetURL - the reset page URL as defined in the policy (see above).
  • $pwResetToken - this is the token that should be passed as the passwordResetToken parameter of the accounts.resetPassword API call.

  • $pwResetLink - By default, this is composed of $pwResetURL?pwrt=$pwResetToken

    $pwResetLink, $pwResetToken, and $pwResetURL are to be used inside the body of the email template. {pwrt} and {apiKey} are used to define placeholders within the URL template.

    Regardless of which placeholders used in the email template, SAP Customer Data Cloud will always append the API key to the URL.

Other parameters that affect the reset password policy are passed in the passwordReset JSON object of accounts.setPolicies. 

Email Policies

Email Verification

Verification emails are sent if they are required by the site policy. Note that the "Email Verification" template is a link verification (the user clicks the link sent out in this template), and not the code verification, which is a separate template. Only one of these policies can apply to a given site.

The following placeholder is available in addition to the ones listed above: $emailVerificationLink - that generates a link the URL configured on the policies page.

When a user clicks the link:

  • They are redirected to that URL together with a verification token. 
  • The status of that email address changes (as reflected in the emails field of the response from accounts.getAccountInfo), from unverified to verified.  

Note that if your policy requires email verification, a verification email will be sent to every new email address added by the user. 

You can also set and get the email verification policy via the accounts API, using accounts.setPolicies and accounts.getPolicies methods. The email verification policy includes the same fields as theVerification Email tab of the Email Templates page:

  • nextURL - The page to which the user will be redirected after verifying their email. If a page isn't specified, SAP Customer Data Cloud provides a URL to display to users: http://accounts.gigya.com/GS/VerifyEmail.aspx.
  • verficationEmailExpiration - how long the verification email is valid (in hours (this is converted to seconds on the server)). The default is 24 hours (86400 seconds).
  • emailTemplates - Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language, using the following format: {<language code1> : <HTML of email template>, <language code2> : <HTML of email template>, ... } Each template applies to a specific language code. If email templates were defined and you set email templates in the API, then they are added to the existing templates or override those with the same language. To remove existing templates, you need to explicitly set them to null.
  • defaultLanguage - The language to use when the requested language is not available. By default, if this field is not modified, the default language is English ("en"). Please make sure that the default language has a corresponding email template definition.

Code Verification

Code verification emails are sent if they are required by the site policy. Note that the "Code Verification" template sends out a verification code to the user, to be entered in an email verification flow, and not the link verification, which is a separate template. Only one of these policies can apply to a given site.

The following placeholder is available in addition to the ones listed above: $code - the code the user should input as part of their registration or email update process.

When a user enters the code:

  • The email provided by the user will be saved to the profile.email field.
  • The recommended best practice is to set the profile.email field permissions to server-only, to enforce the use of the verification flow.
  • After the user enters the code, the email is considered verified.
  • The account becomes a verified account and relevant timestamps are updated accordingly.

You can also set and get the email verification policy via the accounts API, using accounts.setPolicies and accounts.getPolicies methods. The code verification policy is set using the useCodeVerification field of the accountOptions object. The template is configured by passing a codeVerification object, that contains the following fields: defaultLanguage and emailTemplates (an array of language-templates pairs). 

Double Opt-In Confirmation

If you have Subscription Management enabled in your account, you may create subscriptions that require user email confirmation (double opt-in). Use the Email Templates page to edit the email that is sent automatically to potential subscribers.

In addition to the placeholders listed above, the following placeholders are supported:

  • $subscriptionList: includes a list of subscriptions that are pending confirmation for this subscriber. The names are taken from the subscription description. For more information, see Subscription Management
  • $confirmationURL: adds the href for the link (<a>) tag in the email template. Note that you can configure the URL to which subscribers are redirected after confirming their subscription, in the Policies page of the Console. 

New User Welcome

New User Welcome emails are only sent if they are required by site policy (see above). A default template is not provided and you must either setup a template in the New User Welcome tab or use the accounts.setPolicies method. All placeholders listed above are available for this template.

You can also set and get the New User Welcome policy via the accounts API, using the accounts.setPolicies and accounts.getPolicies methods.

In the accountOptions object set:
  • sendWelcomeEmail - Enables the New User Welcome email. When set to true, an email will be sent after completion of registration and email verification, if email verification is required.
  • welcomeEmailTemplates - Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language, using the following format: {<language code1> : <HTML of email template>, <language code2> : <HTML of email template>, ... } Each template applies to a specific language code. If email templates were defined in the console and you set email templates in the API, then they are added to the existing templates or override those with the same language. To remove existing templates, you need to explicitly set them to null.

 

Password Reset Confirmation

Password Reset Confirmation emails are only sent if they are required by site policy (see above). A default template is not provided and you must either setup a template in the Password Reset Confirmation tab or use the accounts.setPolicies method. All placeholders listed above are available for this template.

You can also set and get the Password Reset Confirmation email policy via the accounts API, using accounts.setPolicies and accounts.getPolicies methods.

In the passwordReset object set:
  • sendConfirmationEmail - Enables the Password Reset Confirmation email. When set to true, an email will be sent to the user after successful completion of a password reset.
  • confirmationEmailTemplates - Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language, using the following format: {<language code1> : <HTML of email template>, <language code2> : <HTML of email template>, ... } Each template applies to a specific language code. If email templates were defined in the console and you set email templates in the API, then they are added to the existing templates or override those with the same language. To remove existing templates, you need to explicitly set them to null.

 

Account Deletion Confirmation

Account Deletion Confirmation emails are only sent if they are required by site policy (see above). A default template is not provided and you must either setup a template in the Account Deletion Confirmation tab or use the accounts.setPolicies method. All placeholders listed above are available for this template.

You can also set and get the Account Deletion Confirmation email policy via the accounts API, using accounts.setPolicies and accounts.getPolicies methods.

In the accountOptions object set:
  • sendAccountDeletedEmail - Enables the Account Deletion Confirmation email. When set to true, an email will be sent to the user after successful Deletion of their account.
  • accountDeletedEmailTemplates -Email templates are defined as a JSON object containing a list of email templates, with separate templates for each language, using the following format: {<language code1> : <HTML of email template>, <language code2> : <HTML of email template>, ... } Each template applies to a specific language code. If email templates were defined in the console and you set email templates in the API, then they are added to the existing templates or override those with the same language. To remove existing templates, you need to explicitly set them to null.

TFA Email Confirmation

Used when implementing Risk Based Authentication. Two-factor authentication emails are sent when a login attempt is assigned a relatively high risk level and your RBA Policy AuthLevel is set to 10. Configure the template in the TFA Email Verification tab.

The following placeholders are available in addition to the ones listed above:  

  • $deviceName - The user's device.

  • $countryName - The user's country. 

  • $ipAddress  - The user's IP.  

You can also set and get the TFA Email Confirmation policy via the accounts API, using accounts.setPolicies and accounts.getPolicies methods.

In the twoFactorAuth object set, the providers array includes the authentication providers objects, each with the following fields:

  • name - the identifier assigned to this provider by SAP Customer Data Cloud, e.g., gigyaPhone
  • enabled - Indicates whether this method is enabled for the site. The default value is "false".

  • params - An object where extra information may be stored:

    params: {
     "param1" : "value1",
     "param2" : "value2"
}

Sending an Email From Your Domain

There are cases when you may need to send emails to your users from your own domain name and not the SAP Customer Data Cloud server. If that is the case, notify SAP Customer Data Cloud via the Support tab in the Console.

The steps you then need to perform are as follows:

  • Provide SAP Customer Data Cloud with the IP or IP's of your email server or servers.,
  • Provide SAP Customer Data Cloud with the server credentials (i.e., username and password).
  • Provide SAP Customer Data Cloud with at least one email From address.
    • This needs to match the email address(es) that you will configure in the email template headers of the SAP Customer Data Cloud Console. It can be a valid address, e.g., support@yourdomain.com or an invalid address, e.g., no-reply@yourdomain.com, however, it must match what you configure in the console (so the emails are routed correctly).
  • Let SAP Customer Data Cloud know if your server(s) use a port other than 25 for SMTP.

SAP Customer Data Cloud will then provide you with information to complete the setup process:

  • You will receive an IP or list of IP's to add to your email servers SPF and/or DKIM file.
  • You will then need to add these IP's to your domains white-list.

Changes To Email Templates

Be sure to update the header information in any email templates you have created to reflect the changes (if necessary). If you are using SAP Customer Data Cloud placeholders, these will update automatically.

It is important to note:

  • Server based changes such as these are global for the account (domain/DNS record) and can not be restricted to any single API key.
  • Changing the From address of your email templates without first completing the steps outlined above will have no effect on the server that sends the emails and will only allow users to reply to your specified From address.

Whitelisting

If you are using email forwarding (SMTP relay) to send emails from your own servers, make sure to whitelist the relevant IP addresses. For an updated list, see Whitelisting Gigya IP Addresses. 

 

 

 


 

 

 

 

 

  • No labels