Guide

JavaScript SDK email overview

Suggest Edits

📘

Much of the content on this page deals with a legacy feature of the Akamai Identity Cloud (in this case, the JavaScript SDK). If you are currently an Identity Cloud customer and are using the JavaScript SDK, that SDK is still supported. However, if you’re new to the ​Akamai​ the JavaScript SDK is no longer available. Instead, you should use Hosted Login for your login and registration needs.


The Standard Registration Experience provides transactional emails for common events such as registration confirmation, email verification, and password reset. By default, ​Akamai​ sends emails for you by using Amazon Simple Email Services (Amazon SES). However, customers can choose to send transactional emails using their own email service or provider. Email preference is configured by using the email_method API Client setting. If email_method is set to ses_sync (the default value) then transactional emails are sent by ​Akamai​ and Amazon SES. To send emails using a different service or provider, contact your Akamai representative.

The content for existing emails can be modified by using the Configuration API. In addition, ​Akamai​ can add new emails (to be sent in response to additional registration events) to your flow. Additional information on transactional emails can be found in the Customize transactional emails topic.


📘

When modifying emails, keep in mind that no single line in that email can exceed 998 characters. (Technically, the limit is 1,000 characters, but you must allow for a two-character carriage return-linefeed at the end of each line.) Can you have an email that has 5 lines, each containing 997 characters? Yes. Can you have an email that has 1 lines containing 1,001 characters? No.


The following sections describe the default emails and when they are triggered.


Email template variables

​Akamai​'s Identity Cloud Registration can perform string substitutions in email templates for variables such as the user’s name or the site name where the user registered for personalization and site-specific customization. This allows you to use the same email templates for different websites or applications that share the same Registration configuration. Variables may be pulled from either the user’s record or API client settings found on the Manage Properties page in the Console).

The example email below shows how this will look:

<p>Welcome to {*#settings*}{*site\_name*}{*/settings*}, {*#user*}{*givenName*}{*/user*}!</p>
<p>To complete your new registration, just click on or browse to the URL below to verify this email address.</p>
<p><a href=""></a></p>

User data variables are included by specifying the entity type in a JTL tag wrapper around the schema attribute name. For example, {*#user*}{*givenName*}{*/user*} pulls in data stored in the givenName schema attribute. Any schema attribute may be referenced in this way.

Setting variables are included by specifying the setting name inside of a JTL tag wrapper for settings. For example, {*#settings*}{*site_name}{*/settings}  pulls in the content defined in the site_name API client setting. Any setting may be referenced in this way.

Email templates may also include special JTL link tags that reference API client settings without the {#settings}{/settings} wrapper. These JTL tags may not be modified.

  • {*password_recover_url*}. Generates a unique link for the passwordRecover email by appending an authorization code to the URL defined in the password_recover_url client setting. This code has a configurable duration and is valid for 1 day by default.

  • {*email_verification_url*}.- Generates a unique link for the registrationVerification and emailAddressChanged emails by appending a verification code to the URL defined in the verify_email_url client setting. This code also has a configurable duration and is valid for 1 day by default.


Email template formatting

Transactional emails are always sent in a combined .html and .txt format. Both versions must be supplied for each email and should follow these formatting guidelines:

  • Images. Images must be hosted on your servers and included in the HTML as absolute paths. If you need to include different images per site, variables pulled from the API client settings may reference image URL paths. See Email Template Variables above for more information on how to include variables in email templates.

  • CSS Styling. HTML emails should include inline CSS for styling so that the content can be properly displayed in email client applications. We recommend researching how best to prepare single-file HTML content for email transfers as the structure will be slightly different than a traditional HTML web page.

  • Encoding HTML Entities. Registration encodes HTML entities in the URLs by default, which is the desired behavior in an HTML email but not in a text email. Variables used in the text versions of the emails must include an ampersand (”&“) character before the setting or schema attribute name to suppress the encoding. The example below shows how you would format the same email given in the example above as a text version.

Welcome to {*#settings*}{*&site\_name*}{*/settings*}, {*#user*}{*&givenName*}{*/user*}!
  To complete your new registration, just click on or browse to the URL below to verify this email address.
  {*&email\_verification\_url*}

Updated almost 3 years ago