Customizing emails

When a user interacts with your application, you might want to send a reply or ask for verification. App ID provides default templates that you can use for the interactions. You can also use the templates as a guide and customize your messaging to fit your brand.

App ID uses SendGrid as a mail delivery service. All emails are sent with a single SendGrid account.

Configuring email settings

With App ID, you can choose to use App ID default SendGrid credentials, add your own SendGrid account, or configure your own custom webhook to send email messages in Cloud Directory.

Using the IBM default email provider

By default, App ID uses SendGrid as an email delivery service for Cloud Directory.

Go to the Cloud Directory > Email templates > Email settings page of the service dashboard.
Select Default. The information that you need to input appears.
Configure your Sender details.
1. In From, enter the email address that you want users to receive your emails from.
2. In Sender name, enter the name that you want associated with the "From" email.
3. In Reply-to, enter the email address where you want to receive any replies that someone might have to the email.
Click Test to try your configuration with a test email.
Click Save to enable your configuration.

Adding your own SendGrid account

By using your own SendGrid account to send your Cloud Directory emails, you have full control. You can decide how the emails are sent, use your own domain name, and define your sender details. With custom email settings, you can reduce the chances of an email getting filtered as spam while also furthering brand recognition for your application.

A direct connection to your email provider can help you to get information about individual messages such as the number of people that open the emails and which messages were not delivered. You can also see overall statistics that you can use to better manage your email campaigns.

Don't have a SendGrid account? Sign up.

Go to the Cloud Directory > Email templates > Email settings page of the service dashboard.
Select SendGrid. The information that you need to input appears.
In SendGrid API key, enter your API key.
Configure your Sender details.
1. In From, enter the email address that you want users to receive your emails from.
2. In Sender name, enter the name that you want associated with the "From" email.
3. In Reply-to, enter the email address where you want to receive any replies that someone might have to the email.
Click Test to try your configuration with a test email.
Click Save to enable your configuration.

Customizing your email provider

By defining your own custom extension point to send your Cloud Directory emails, you have full control. You can decide how the emails are sent, use your own domain name, and define your sender details. With custom email settings, you can reduce the chances of an email getting filtered as spam while also furthering brand recognition for your application.

Configuring a custom provider with the GUI

You can use the service dashboard to configure your custom provider.

Go to the Cloud Directory > Email templates > Email settings page of the service dashboard.
Select Custom. The information that you need to input appears.
In Webhook, enter your custom extension URL.
Select an Authorization type. You can choose from the following options:
- None: The webhook endpoint or URL, does not require an authorization header.
- Basic: The webhook endpoint requires an HTTP authorization header with every request in the form of a username and password.
- Authorization headers: The webhook request requires that you pass the authorization information for your endpoint in an HTTP authorization. For example, you might pass an OAuth 2.0 token: Authorization: Bearer eyJraWQiOiIyMDIwMDEyNTE2MzMiLCJhbGciOiJSUzI1NiJ9.eyJpYW1faWQiOiJJ.
Configure your Sender details.
1. In From, enter the email address that you want users to receive your emails from.
2. In Sender name, enter the name that you want associated with the "From" email.
3. In Reply-to, enter the email address where you want to receive any replies to the email.
Click Test to try your configuration with a test email.
Click Save to enable your configuration.

Configuring a custom provider with the API

You can use the Cloud Directory management APIs to configure your custom email sender.

Configure an extension point that can listen for a POST request. The endpoint must be able to:

Read the payload that comes from App ID.
Send the email from your custom provider.
Optionally, validate the JSON payload that is returned by App ID was not altered by a third party in any way. A string that is formatted as {"jws": "jws-format-string"} is returned that contains your tenant ID, the issuer of your JWS token, the timestamp of when the message was sent, a unique transaction ID, and the actual message information that includes your sender details and email body content.

Your extension point might look similar to the following example:

const sgMail = require('@sendgrid/mail');
const {promisify} = require('bluebird');
const request = promisify(require('request'));
const jwtVerify = promisify(require('jsonwebtoken').verify);
const jwtDecode = require('jsonwebtoken').decode;
const jwkToPem = require('jwk-to-pem');

async function obtainPublicKeys() {
   // Your {{site.data.keyword.appid_short_notm}} instance tenant ID
   const tenantId = '<tenantID>';

   // Send request to {{site.data.keyword.appid_short_notm}}'s public keys endpoint
   const keysOptions = {
   method: 'GET',
   url: `https://<region>.appid.cloud.ibm.com/oauth/v4/$<tenantID>/publickeys`
   };
   const keysResponse = await request(keysOptions);
   return JSON.parse(keysResponse.body).keys;
}

async function verifySignature(keysArray, kid, jws) {
   const keyJson = keysArray.find(key => key.kid === kid);
   if (keyJson) {
   const pem = jwkToPem(keyJson);
   await jwtVerify(jws, pem);
   return;
   }
   throw new Error ("Unable to verify signature");
}

async function verifyAndSendMail(jws) {
   // The API key for Sendgrid
   const sgApiKey = '<SengridApiKey>';

   // Init Sendgrind
   sgMail.setApiKey(sgApiKey);

   // Decode message to get information
   const data = jwtDecode(jws, {complete: true});

   // Extract kid from header
   const kid = data.header.kid;

   const keysArray = await obtainPublicKeys();

   // Verify the signature of the payload with the public keys
   await verifySignature(keysArray, kid ,jws);

   // Send the email with Your Sendgrid account
   const message = data.payload.message;
   const msg = {
   to: message.to,
   from: message.from.address,
   subject: message.subject,
   html: message.body,
   };
   console.log(`Sending email to ${message.to}`);
   let sendgridResponse = await sgMail.send(msg);

   return {result : 'email_sent',sendgridResponse};
}

Make a PUT request to the /management/v4/<tenantID>/config/cloud_directory/email_dispatcher to provide your webhook URL. Optionally, you can provide authorization information. Supported authorization types include: Basic authorization and constant authorization header value.

curl -X PUT https://<region>.appid.cloud.ibm.com/management/v4/<tenantID>/config/cloud_directory/email_dispatcher' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <IAMToken>' \
-d '{
   "provider": "custom",
   "custom": {
   "url": "https://example.com/send_mail",
   "authorization": {
      "type": "basic",
      "username": "<username>",
      "password": "<password>"
      }
   }
   }'

Verify that your configuration is correctly set up by testing your email dispatcher. Use the test API to trigger a request to your configured custom email sender.

Email templates

When you send messages to your users, you can use any combination of the following templates. Or, you can edit the templates to customize your message.

In addition to the following message types, you can also take advantage of the MFA templates.

For further customization, you can use parameters in your messages. Check out the following table to see the parameters that you can use in all the message types.

Table 1. The parameters that you can use in your messages to users
Parameter	Description
`%{display.logo}`	Displays the image that you configured for your Login Widget.
`%{user.displayName}`	Displays the screen name a user chose to use when interacting with the app.
`%{user.email}`	Displays the user's registered email address.
`%{user.username}`	Displays the user's specified username when the authentication method is set to username and password.
`%{user.firstName}`	Displays the user's specified given name.
`%{user.formattedName}`	Displays the user's full name.
`%{user.lastName}`	Displays the user's specified surname.

Email: Welcome

When a user signs up for your application, you might want to send them a message that welcomes them to your app.

Go to the Cloud Directory > Email templates > Welcome email tab of the service dashboard.
Set Welcome email to Enabled.
Customize the content of your message. You can add parameters and insert images by using the UI. To change the language of the message, you can use the APIs to set the language. However, you are responsible for the content and conversion of the message. Check out the following table to see the list of tables that you can use in this message and all the other messages that you can send. If a user does not supply the information that is pulled by the parameter, it appears blank.
Click Save.

Email: Verification

When a user signs up for your application by using their email, you can send them an email that asks them to confirm their identity. By requesting a verification, you limit the number of fake accounts that can sign up for your app. You can restrict access to your app until a user verifies their email, or use it as a way to manage which users you create profiles for.

Users who are manually added via the App ID dashboard or the create user API do not automatically receive this email.

Go to the Cloud Directory > Email templates > Email verification tab of the service dashboard.
Set Email verification to Enabled.
Set Allow users to sign in to your app without first verifying their email address to Yes. When set to yes, users are able to interact with your application after they sign up, but before they verify their email address. The default setting is no.

Customize the content of your message. You can add parameters and insert images by using the UI. To change the language of the message, you can use the APIs to set the language. However, you are responsible for the content and conversion of the message. Check out the following table to see the different parameters that you can use in your message. If a user does not supply the information that is pulled by the parameter, it appears blank.

Table 2. Parameters that you can use in messages that are related to verification
Parameter	Description
`%{linkExpiration.hours}`	Displays the number of hours the link is valid.
`%{linkExpiration.minutes}`	Displays the number of minutes the link is valid.
`%{verify.code}`	Displays a one-time verification URL.
`%{verify.link}`	Displays the action URL that you specified in settings.

You can also use the message parameters that are listed in the Welcome message section.

Define an expiration time for the action URL. The URL expiration is the amount of time, in minutes, that a user must complete the action before the verification link expires. This setting also affects the amount of time that your reset password link is valid.
Enter a URL for the page that you want to display after a user verifies their email in the Thank you page URL box. If you choose to leave this field blank, an App ID default page is displayed.
Click Save.

Email: Reset password

When a user interacts with your app, they might forget their password or need to update it. You can customize the email response to their request. When a user requests a change to their password, the password remains unchanged until they click the link in this email.

Go to the Cloud Directory > Email templates > Reset password tab of the service dashboard.
Set Forgot password email to Enabled.

Table 3. Parameters that you can use in messages that are related to forgotten passwords
Parameter	Description
`%{linkExpiration.hours}`	Displays the number of hours that the link is valid.
`%{linkExpiration.minutes}`	Displays the number of minutes that the link is valid.
`%{resetPassword.code}`	Displays a one-time passcode as part of the URL. This means that each person would have a different code. Example: `https://us-south.appid.cloud.ibm.com/wfm/verify/6574839563478`
`%{resetPassword.link}`	Displays the link that a user clicks to reset their password.

You can also use the message parameters that are listed in the Welcome message section.

Define an expiration time for the action URL. The URL expiration is the amount of time, in minutes, that a user must complete the action before the verification link expires. This setting also affects the amount of time that your reset password link is valid.
Enter a URL for the page that you want to display after a user verifies their email in the Reset password page URL box. If you choose to leave this field blank, an App ID default page is displayed.
Click Save.

Email: Password change

You can notify a user when their password is updated. The notification can be helpful if they did not request that their password be changed. They can take the proper steps to resecure their account.

Go to the Cloud Directory > Email templates > Password change tab of the service dashboard.
Set Password changed email to Enabled.

Table 4. Parameters that you can use in messages that are related to changing a password
Parameter	Description
`%{passwordChangeInfo.time}`	Displays the time at which a new password went into effect.
`%{passwordChangeInfo.ipAddress}`	Displays the IP address from which the password change was requested.

You can also use the message parameters that are listed in the Welcome message section.

Click Save.

Supported languages

You can use the language management APIs to set the language in which your user communication can be written. However, only English is available out of the box. You are responsible for the conversion of the messages. After you set the configuration with the API, the GUI updates so that you are able to change the template text.

Table 6. Languages that are supported
Code	Language	Region
`af-ZA`	Afrikaans	South Africa
`sq-AL`	Albanian	Albania
`am-ET`	Amharic	Ethiopia
`ar-DZ`	Arabic	Algeria
`ar-BH`	Arabic	Bahrain
`ar-EG`	Arabic	Egypt
`ar-IQ`	Arabic	Iraq
`ar-JO`	Arabic	Jordan
`ar-KW`	Arabic	Kuwait
`ar-LB`	Arabic	Lebanon
`ar-LY`	Arabic	Libya
`ar-MR`	Arabic	Mauritania
`ar-MA`	Arabic	Morocco
`ar-OM`	Arabic	Oman
`ar-QA`	Arabic	Qatar
`ar-SA`	Arabic	Saudi Arabia
`ar-SY`	Arabic	Syria
`ar-YE`	Arabic	Tunisia
`ar-AE`	Arabic	United Arab Emirates
`ar-YE`	Arabic	Yemen
`hy-AM`	Armenian	Armenia
`as-IN`	Assamese	India
`az-AZ`	Azerbaijani	Azerbaijan
`eu-ES`	Basque	Spain
`be-BY`	Belarusian	Belarus
`bn-BD`	Bengali	Bangladesh
`be-BY`	Belarusian	Belarus
`bn-BD`	Bengali	Bangladesh
`bn-IN`	Bengali	India
`bs-Latn-BA`	Bosnian	Bosnia
`bg-BG`	Bulgarian	Bulgaria
`my-MM`	Burmese	Myanmar
`ca-ES`	Catalan	Spain
`zh-Hans-CN`	Chinese-simplified	China
`zh-Hans-SG`	Chinese-simplified	Singapore
`zh-Hant-HK`	Chinese-traditional	Hong Kong S.A.R. of China
`zh-Hant-MO`	Chinese-traditional	Macao S.A.R. of the PRC
`zh-Hant-TW`	Chinese-traditional	Taiwan
`hr-HR`	Croatian	Croatia
`cs-CZ`	Czech	Czech Republic
`da-DK`	Danish	Denmark
`nl-BE`	Dutch	Belgium
`nl-NL`	Dutch	The Netherlands
`en-AU`	English	Australia
`eu-BE`	English	Belgium
`en-CM`	English	Cameroon
`eu-CA`	English	Canada
`en-GH`	English	Ghana
`eu-HK`	English	Hong Kong S.A.R. of China
`en-IN`	English	India
`en-IE`	English	Ireland
`en-KE`	English	Kenya
`en-MU`	English	Mauritius
`en-NZ`	English	New Zealand
`en-NG`	English	Nigeria
`en-PH`	English	Philippines
`en-SG`	English	Singapore
`en-ZA`	English	South Africa
`en-TZ`	English	Tanzania
`en-GB`	English	United Kingdom
`en-US`	English	United States
`en-ZM`	English	Zambia
`en`	English
`et-EE`	Estonian	Estonia
`fil-PH`	Filipino	Philippines
`fi-FI`	Finnish	Finland
`fr-DZ`	French	Algeria
`fr-CM`	French	Cameroon
`fr-CD`	French	Democratic Republic of the Congo
`fr-BE`	French	Belgium
`fr-CA`	French	Canada
`fr-FR`	French	France
`fr-CI`	French	Ivory Coast (Côte d’Ivoire)
`fr-LU`	French	Luxembourg
`fr-MR`	French	Mauritania
`fr-MU`	French	Mauritius
`fr-MA`	French	Morocco
`fr-SN`	French	Senegal
`fr-CH`	French	Switzerland
`fr-TN`	French	Tunisia
`gl-ES`	Galician	Spain
`lg-UG`	Ganda	Uganda
`ka-GE`	Georgian	Georgia
`de-AT`	German	Austria
`de-DE`	German	Germany
`de-LU`	German	Luxembourg
`de-CH`	German	Switzerland
`el-GR`	Greek	Greece
`gu-IN`	Gujarati	India
`ha-NG`	Hausa	Nigeria
`he-IL`	Hebrew	Israel
`hi-IN`	Hindi	India
`hu-HU`	Hungarian	Hungary
`is-IS`	Icelandic	Iceland
`ig-NG`	Igbo	Nigeria
`id-ID`	Indonesian	Indonesia
`it-IT`	Italian	Italy
`it-CH`	Italian	Switzerland
`ja-JP`	Japanese	Japan
`kn-IN`	Kannada	India
`kk-KZ`	Kazakh	Kazakhstan
`km-KH`	Khmer	Cambodia
`rw-RW`	Kinyarwanda	Rwanda
`kok-IN`	Konkani	India
`ko-KR`	Korean	South Korea
`lo-LA`	Lithuanian	Lithuania
`lv-LV`	Latvian	Latvia
`lt-LT`	Khmer	Cambodia
`mk-MK`	Macedonian	Macedonia
`ms-Latn-MY`	Malay-Latin	Malaysia
`ml-IN`	Malayalam	India
`mt-MT`	Maltese	Malta
`mr-IN`	Marathi	India
`mn-Cyrl-MN`	Mongolian-Cyrillic	Mongolia
`ne-IN`	Nepali	India
`ne-NP`	Nepali	Nepal
`nb-NO`	Norwegian Bokmål	Norway
`nn-NO`	Norwegian Nynorsk	Norway
`or-IN`	Oriya (Odia)	India
`om-ET`	Oromo	Ethiopia
`pl-PL`	Polish	Poland
`pt-AO`	Portuguese	Angola
`pt-BR`	Portuguese	Brazil
`pt-MO`	Portuguese	Macao S.A.R. of the PRC
`pt-MZ`	Portuguese	Mozambique
`pt-PT`	Portuguese	Portugal
`pa-IN`	Punjabi	India
`ro-RO`	Romanian	Romania
`ru-RU`	Russian	Russia
`sr-Cyrl-RS`	Serbian-Cyrillic	Serbia
`sr-Latn-ME`	Serbian-Latin	Montenegro
`sr-Latn-RS`	Serbian-Latin	Serbia
`si-LK`	Sinhala	Sri Lanka
`sk-SK`	Slovak	Slovakia
`sl-SI`	Slovenian	Slovenia
`es-AR`	Spanish	Argentina
`es-BO`	Spanish	Bolivia
`es-CL`	Spanish	Chile
`es-CO`	Spanish	Colombia
`es-CR`	Spanish	Costa Rica
`es-DO`	Spanish	Dominican Republic
`es-EC`	Spanish	Ecuador
`es-SV`	Spanish	El Salvador
`es-GT`	Spanish	Guatemala
`es-HN`	Spanish	Honduras
`es-MX`	Spanish	Mexico
`es-NI`	Spanish	Nicaragua
`es-PA`	Spanish	Panama
`es-PY`	Spanish	Paraguay
`es-PE`	Spanish	Peru
`es-PR`	Spanish	Puerto Rico
`es-ES`	Spanish	Spain
`es-US`	Spanish	United States
`es-UY`	Spanish	Uruguay
`es-VE`	Spanish	Venezuela
`sw-KE`	Swahili	Kenya
`sw-TZ`	Swahili	Tanzania
`sv-SE`	Swedish	Sweden
`ta-IN`	Tamil	India
`te-IN`	Telugu	India
`th-TH`	Thai	Thailand
`tr-TR`	Turkish	Turkey
`uk-UA`	Ukrainian	Ukraine
`ur-IN`	Urdu	India
`ur-PK`	Urdu	Pakistan
`uz-Cyrl-UZ`	Uzbek-Cyrillic	Uzbekistan
`uz-Latn-UZ`	Uzbek-Latin	Uzbekistan
`vi-VN`	Vietnamese	Vietnam
`cy-GB`	Welsh	United Kingdom
`yo-NG`	Yoruba	Nigeria
`zu-ZA`	Zulu	South Africa