Modify transactional emails

Suggest Edits

Transactional emails are emails automatically sent by Identity Cloud in response to specific user events or actions. Did a user just register with your website? An email is sent confirming the registration and asking the user to verify their email address. Did a user’s password just get changed? An email is sent notifying the user that the password has changed, and making sure that the user was the one who changed it.

Here’s a slightly-more fleshed-out example. Suppose a user arrives at your website only to realize that they’re forgotten their password. Is this user out of luck? No, not as long as they click the Forgot Password? link that appears on the sign-in screen:

If a user clicks Forgot Password? and enters their email address on the Password Reset form, they’ll be sent a transactional email similar to the following:

In turn, the user can click the link enclosed in the email and, if all goes well, reset their password.

For this article, we’re not really concerned with the password reset flow; that’s just an example of how the system works. Instead, our goal is to show you how you can modify the subject line and the body text of your transactional emails. Are you perfectly happy with those emails as-is? Great; then you don’t need to read this article after all. But if you are interested in modifying your transactional emails, then you might want to keep reading.

Note that, at this point in time all you can do is change the subject line or the body text of your emails: you can’t create new transactional emails nor can you delete existing emails. In addition, you can’t specify when transactional emails will (or won’t) be sent: it’s up to Hosted Login to determine that. However, if you specify an email name you can look in the flow and find instances where it’s referenced. For example, here we can see that the passwordRecover email is sent from the forgotPasswordForm form:

You can’t change that, but at least you can figure when, and why, transactional emails get sent.

Retrieve information about your transactional emails

In order to modify your transactional emails you first need to know which emails are available to you. That information can be retrieved from the mails section of your Hosted Login flow:

You can retrieve this same information by calling the /config/{appId}/flows/{flow}/locales/{locale}/mailTemplates operation:

curl -X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

That returns the names of all your transactional email templates:

[
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/ccp\_emailAddressChanged",
"name": "ccp_emailAddressChanged"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/ccp\_passwordRecover",
"name": "ccp_passwordRecover"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/ccp\_registrationVerification",
"name": "ccp_registrationVerification"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/emailAddressChanged",
"name": "emailAddressChanged"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/passwordChanged",
"name": "passwordChanged"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/passwordRecover",
"name": "passwordRecover"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/registrationConfirmation",
"name": "registrationConfirmation"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/registrationVerification",
"name": "registrationVerification"
    },
    {
        "\_self": "/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-us/mailTemplates/resendVerification",
        "name": "resendVerification"
    }
]

So what do we do now that we know the names of our email templates? Well, for, starters, let’s take a look at how a transactional email is configured in the flow. If we look at passwordRecover in the mails section, we’ll see something similar to this:

For now, we only care about these three properties:

htmlBody. The HTML-formatted version of the email.
subject. The subject line of the email.
textBody. The plain-text version of the email.

Like other text elements used in Hosted Login (such as the [text that appears on your Hosted Login screens), the actual email text and subject line don’t show up in the mails section. Instead, you see a translation key (e.g., 6b3357ec757e3b4da224cb4a774f69f5 for the htmlBody property). If you look up that translation key, you’ll see something similar to this (at least for the en-US translation):

That’s the HTML version of the passwordRecover email. If you take a peek at the translation key (976dce129062e08b8d30d7d35700c724) for the text version of that same you’ll see something like this:

And, of course, you can always use an API call to return this same information. For example:

curl X GET \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-US/mailTemplates/passwordRecover/body' \
 --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U='

Do that and, by default, you’ll get back the HTML version of the email:

<p>
     Hi there!
</p>
<p>
     We received a request to reset the password associated with this email address. If you made this request, please follow the instructions below.
</p>
<p>
     Click the link below to reset your password using our secure server:<br/><a href=""></a>
</p>
<p>
     If you did not request to have your password reset, you can safely ignore this email.
</p>
<p>
     Rest assured that your customer account is safe.

</p>
<p>
     If clicking the link doesn't seem to work, you can copy and paste the link into your browser's address window, or retype it there. Once you have returned to {*#settings*}{*site\_name*}{*/settings*}, we will provide instructions for resetting your password.
</p>

And what if you’d like to see the text version of the email instead? In that case, add the Accept header to your API call and set the value of this header to text/plain. In Postman, that looks similar to this:

To use this same command to return the HTML version, set the value of the Accept header to text/html.

That’s good to know, but we still have a question: how do we change the text of a transactional email. Fair enough; we’ll show you how to do that in a minute. Before we do, however, we need to mention those odd-looking bits of text that you’ll see in the default emails, text that might come in handy if you do decide to modify your emails:

{*#settings*}{*&site_name*}{*/settings*}. Name of your website or app. In your application client settings, this is the value of the site_name setting.
{*#user*}{*&givenName*}{*/user*}. The user’s given name (first name). This value is taken from the givenName attribute in the user’s user profile.
{*password_recover_url*}. The base URL used when generating a password reset link. In your application client settings, this is the value of the password_recover_url setting.
{*email_verification_url*}. The base URL used when generating an email verification link. In your API client settings, this is the value of the verify_email_url setting.

These odd-looking pieces of text are JTL (Janrain Templating Language) tags, and they function similar to a variable in a mathematical equation. For example, take the following math equation:

2 + X = 5

In that equation, X is a variable representing the number 3. Now, consider this transactional email text:

Welcome to the {*#settings*}{*&site_name*}{*/settings*} website!

In this case, the JTL tag {*#settings*}{*&site_name*}{*/settings*} is a variable representing the name of your website. In the email sent to a user, they won’t see the JTL tag. Instead, they’ll see something similar to this:

Welcome to the Identity Cloud Documentation website!

This is neither the time nor the place for a complete discussion of JTL tags, but the four tags we showed you a minute ago are the ones used by default on Hosted Login emails, which means that you might want to use them as well.

📘
Here’s something to keep in mind: the {*#user*}{*&givenName*}{*/user*} tag references the user’s first name (the givenName attribute). That information is only available if a user has successfully logged on. In turn, that means that the user’s first name can’t be used on, say, the Forgot Password email. Why not? That’s right: because the user isn’t logged on at the time the email is requested and sent.

Change the HTML version of an email

To change the text of a transactional email, use the PUT method and the /config/{AppID}/flows/{flow}/locales/{locale}/mailTemplates/{template}/body operation, and include the email’s new HTML-formatted text in the request body. For example, this command changes the text of the passwordRecover email (in this case, we simply made the text a bit shorter):

curl -X PUT \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-US/mailTemplates/passwordRecover/body' \
 --header 'Content-Type: text/html' \
 --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
 --data-raw
 '<p>
 We received a request to reset the password associated with this email address. If you made this request, please follow the instructions below.</p><p> Click the link below to reset your password:<br/>
 <a href=""></a></p>
 '

If your API call succeeds, the entry for translation key 6b3357ec757e3b4da224cb4a774f69f5 will now look like this:

And if you click the Forgot Password?link the email sent to you should look like the following:

That’s cool, but guess what: it gets even better. As you know, this transactional email is formatted by using HTML; that means that you can format your emails by using pretty much any HTML markup (and inline CSS styles) that you want. For example, this very simple request body uses inline styles to set the font color of the first paragraph to red (style="color:red") and the background color of the second paragraph to yellow (style="background-color:yellow"):

<p style="color:red">
     We received a request to reset the password associated with this email address. If you made this request, please follow the instructions below.
</p>
<p style=”background-color:yellow”>
     Click the link below to reset your password:<br/><br/>
<a href=""></a>
</p>

The net result might be an email that only its mother could love, but it does demonstrate how CSS can be used to enhance your messages:

Of course, if you know a little something about CSS you can create much more aesthetically-pleasing emails. That includes the following example, in which the reset password hyperlink has been turned into a button:

That’s a little more like it.

Change the plain-text version of an email

The preceding information is great if you want to change the HTML version of a transactional email. But what if you want to modify the plain-text version of, say, the passwordRecover email? In that case, you need to do a few things:

Don’t include any HTML formatting in the mail. That should be fairly obvious, but we thought we’d remind you, just in case.
Just like you did when retrieving the plain-text version of an email, add the Accept header to your API call and set the value to text/plain.
Make sure the Content-Type header of that API call is also set to text/plain.
Keep in mind that line breaks are ignored when the value is written to the flow. If you need line breaks in your email, use \n.

📘
Good question: how do you know which version of your email (HTML or plain-text) a user will receive? Well, to be honest, you don’t know. Each time the Identity Cloud sends a transactional email, that email is sent in both an HTML and a plain-text version; it’s then up to the user’s email client to choose which email will actually be displayed. Typically that will be the HTML version, but some users might prefer plain-text emails. And that’s what they’ll get.

In other words, create an API call that looks something like this:

curl -X PUT \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-US/mailTemplates/passwordRecover/body' \
 --header 'Content-Type: text/plain' \
 --header 'Accept: text/plain' \
 --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
 --d 'We received a request to reset the password associated with this email address. If you made this request, please follow the instructions below.\n\nClick the link below to reset your password:\n\n
'

Change the subject line of an email

To change the subject line of a transactional email you use a similar approach, this time employing the PUT method and the /config/{appId}/flows/{flow}/locales/{locale}/mailTemplates/{template}/subject operation. We should point out that there’s only one subject line per transactional email: the HTML version of the email and the plain text version of the email use the same subject line. Oh, and you can’t format the subject line in any way: subject lines are plain-text only.

📘
Well, except for a JTL tag such as {*#settings*}{*&site_name*}{*/settings*}.

About the only other thing you need to know is that the subject line should be formatted as plain text within your body tag, with no JSON formatting. For example:

'Changing Your Identity Cloud Password'

All of that is a long way of saying that an API call similar to this is what you need in order to change the subject line for the passwordRecover email:

curl -X PUT \
 'https://v1.api.us.janrain.com/config/79y4mqf2rt3bxs378kw5479xdu/flows/testFlow/locales/en-US/mailTemplates/passwordRecover/subject' \
 --header 'Content-Type: text/plain' \
 --header 'Authorization: Basic eTR4Zmc2ZjQ0bXNhYzN2ZXBqanZ4Z2d6dnQzZTNzazk6OTVjY3hrN2N6YnZ1eng2ZHB0ZTVrOXA2ZGo1Ynpla3U=' \
 --d 'Changing Your Identity Cloud Password'

Will that really work? See for yourself:

Change your email sender address

By default, transactional emails are sent from the email address noreply@janrain.com:

If that works for you, hey, that’s great: that means there’s nothing you have to do. If it doesn’t work for you, however, it’s easy to change the sent from address. For example:

As it turns out, the sender address is configured by using the email_sender_address setting, a setting that can be applied at the application level (in which case it applies, by default, to all your API clients) or can be set individually for each API client. When setting the sender address, use the following syntax:

"Friendly Name" <*email_address>

Which, in real-life, looks similar to this:

"Identity Cloud Documentation" noreply@janrain.com

The email_sender_address can be changed by calling the /config/{appId}/settings operation. For example:

curl -X PUT \
 'https://v1.api.us.janrain.com/config/hevwjvt8j7cym5hbbzdu8mv6aj/settings' \
 --header 'Content-Type: application/json' \
 --d '
 {
 "email_sender_address": "Identity Cloud Documentation'\'' <noreply@akamai.com>"
 }'

If you’d rather make the change at the client level, use the /config/{appId}/clients/{client_id}/settings operation instead.

And, if you prefer, you can make this same change in Console:

The one thing to watch out for is this: not only must you use a real email address here, but that email address must be tested and verified by Akamai >> before it can be used. For example, if you’re in the Console and you try to enter an unverified email address, you’ll generate an error like this one:

If you want to change your email sender address, contact your Akamai representative and let them know the address you’d like to use. Your Akamai >> rep will get the verification ball rolling, a process that should take less than 24 hours from start to finish. As soon as you have a verified email address then you can change the email_sender_address setting.

Updated almost 2 years ago