When your app uses rich email service templates, brainCloud sends its authentication emails through your own SendGrid account, using templates that you design in SendGrid. This article explains how to choose which SendGrid template is used for each kind of email, how to provide different templates for different languages, and which variables brainCloud fills in for you.
These settings are on the Rich Email Service Templates tab of the App > Design > Authentication > Email Authentication page.
Before you start
The SendGrid integration is configured and enabled on App > Design > Integrations > Manage Integrations. Your SendGrid API key needs Mail Send (full) and Template Engine (read) permissions; without Template Engine access, brainCloud can't list your templates.
On the Email Authentication tab, Send Verification Email Using SendGrid is checked and Authentication Templates is set to Use rich email service templates (recommended). The Rich Email Service Templates tab is disabled while Use simple plain text is selected.
You have created your templates in the SendGrid dashboard (Email API > Dynamic Templates). Dynamic templates are recommended.
Step 1: Assign a template to each use case
The tab shows one dropdown for each email brainCloud can send:
Delete Account: sent when a user requests that their account be deleted. It contains the confirmation link.
Password Reset: sent when a user requests a password reset. It contains the reset link.
Password Reset Confirmation: sent after the password has been changed, if Send Password Reset Confirmation Email is enabled.
User Locked: sent when login brute-force protection locks an account, if notifications are enabled on App > Design > Security > User.
Verification Email: sent when a user registers an email identity. It contains the verification link.
Verification Email Confirmation: sent after the user verifies, if Send Confirmation Email is enabled.
Each dropdown lists the templates in your SendGrid account by name; both dynamic and legacy templates are included. Choose the template for each email, then click Save.
Tip: Click Test next to any dropdown to send the selected template to the email address of your portal login. Test emails use sample values (for example, userName jDoe), so only the basic variables are filled in.
Step 2 (optional): Add templates for other languages
You can send users a template in their own language:
Make sure the language is enabled for your app on App > Design > Core App Info > Localization. The Add... dialog only offers the app's supported languages.
On the Rich Email Service Templates tab, click + Add... next to Language and choose one or more languages.
Choose a language in the Language dropdown. The template dropdowns now show the assignments for that language.
Assign a SendGrid template (for example, a translated copy such as Password Reset – FR) to each email, then click Save.
To remove a language, select it and click Delete.... The app's default language can't be deleted.
How brainCloud picks the template
brainCloud uses the language code on the user's profile, which is normally set by the client SDK from the device language when the user authenticates. If the profile has no language, brainCloud uses the app's default language.
If no template is assigned for that language, brainCloud falls back to the English (en) template.
Recommendation: always assign templates for English, even if your app's default language is something else. Then every user receives an email, even when their language has no template of its own.
Step 3: Use brainCloud's variables in your templates
brainCloud passes user and app details to SendGrid with every email. How you reference them depends on the type of template:
Dynamic templates (template ID starts with
d-) use Handlebars syntax, for example{{appName}}and{{webUrl}}.Legacy templates use dash-wrapped substitution tags, for example
-appName-and-webUrl-.
Variable | Value |
| The action link. It is provided only for Verification Email, Password Reset and Delete Account, and these templates must include it. |
| Your app's name and icon URL |
| The user's profile ID, name and email address |
| The user's country and language codes |
| The user's profile picture URL |
| Login history (ISO-8601 timestamps and a count) |
| The user's spend and XP statistics |
| The user's balance of each virtual currency, for example |
| Your branding and contact details, provided only when Self-Service branding is enabled for the app |
Example dynamic template snippet for the password reset email:
<p>Hi {{userName}},</p>
<p>We received a request to reset your {{appName}} password.</p>
<p><a href="{{webUrl}}">Reset my password</a></p>Troubleshooting
The dropdowns are empty: check that the SendGrid integration is enabled and that the API key has Template Engine (read) permission.
A user received the English email instead of their language: check the language code on their profile (User > User Summary), and make sure a template is assigned for that exact language.
Links are missing from the email: make sure the template uses
{{webUrl}}(dynamic) or-webUrl-(legacy), and that it is assigned to Verification Email, Password Reset or Delete Account.