自訂電子郵件

當使用者與您的應用程式互動時,您可能想要傳送回覆或要求驗證。App ID 提供預設範本,您可以用來進行互動。 您也可以使用範本作為指引,並自訂傳訊以符合您的品牌。

App ID 用途 SendGrid 作為郵件遞送服務。 所有電子郵件都是使用單一 SendGrid 帳戶所傳送。

配置電子郵件設定

透過 App ID,您可以選擇使用 App ID 預設 SendGrid 憑證、新增您自己的 SendGrid 帳戶,或設定您自己的自訂 webhook 以在 Cloud Directory 中傳送電子郵件訊息。

使用 IBM 預設電子郵件提供者

依預設,App ID 會使用 SendGrid 作為 Cloud Directory 的電子郵件遞送服務。

  1. 移至服務儀表板的 Cloud Directory > Email templates > Email settings 頁面。

  2. 選取 預設值。 即會出現您需要輸入的資訊。

  3. 設定您的寄件者詳細資訊

    1. 寄件者中,輸入您要使用者從中接收電子郵件的電子郵件位址。

    2. 寄件者名稱中,輸入您要與「寄件者」電子郵件相關聯的名稱。

    3. 回覆中,輸入您要在其中接收某人可能對電子郵件具有之任何回覆的電子郵件位址。

  4. 按一下 測試,以使用測試電子郵件來嘗試您的配置。

  5. 按一下儲存以啟用您的組態。

新增您自己的 SendGrid 帳戶

透過使用您自己的 SendGrid 帳戶來傳送 Cloud Directory 電子郵件,您可以完全控制。 您可以決定電子郵件的傳送方式、使用您自己的網域名稱,以及定義寄件者詳細資料。 使用自訂電子郵件設定,您可以減少電子郵件被過濾為垃圾郵件的機會,同時還可以進一步促進應用程式的品牌識別。

與電子郵件提供者的直接連線可協助您取得個別訊息的相關資訊,例如開啟電子郵件的人員數目及未遞送哪些訊息。 您也可以查看可用來更妥善管理電子郵件行銷活動的整體統計資料。

沒有 SendGrid 帳戶? 註冊

  1. 移至服務儀表板的 Cloud Directory > Email templates > Email settings 頁面。

  2. 選取 SendGrid。 即會出現您需要輸入的資訊。

  3. SendGrid API 金鑰中,輸入 API 金鑰。

  4. 設定您的寄件者詳細資訊

    1. 寄件者中,輸入您要使用者從中接收電子郵件的電子郵件位址。

    2. 寄件者名稱中,輸入您要與「寄件者」電子郵件相關聯的名稱。

    3. 回覆中,輸入您要在其中接收某人可能對電子郵件具有之任何回覆的電子郵件位址。

  5. 按一下 測試,以使用測試電子郵件來嘗試您的配置。

  6. 按一下儲存以啟用您的組態。

自訂電子郵件提供者

透過定義您自己的自訂延伸點來傳送 Cloud Directory 電子郵件,您可以完全控制。 您可以決定電子郵件的傳送方式、使用您自己的網域名稱,以及定義寄件者詳細資料。 使用自訂電子郵件設定,您可以減少電子郵件被過濾為垃圾郵件的機會,同時還可以進一步促進應用程式的品牌識別。

與電子郵件提供者的直接連線可協助您取得個別訊息的相關資訊,例如開啟電子郵件的人員數目及未遞送哪些訊息。 您也可以查看可用來更妥善管理電子郵件行銷活動的整體統計資料。

使用 GUI 來配置自訂提供者

您可以使用服務儀表板來配置自訂提供者。

  1. 移至服務儀表板的 Cloud Directory > Email templates > Email settings 頁面。

  2. 選擇自訂。 即會出現您需要輸入的資訊。

  3. Webhook 中,輸入您的自訂分機 URL。

  4. 選擇授權類型。 您可以從下列選項選擇:

    • :webhook 端點或 URL,不需要授權標頭。
    • 基本:Webhook 端點要求每個請求都有 HTTP 授權標頭,形式為使用者名稱和密碼。
    • 授權標頭:Webhook 請求要求您在 HTTP 授權中傳遞您端點的授權資訊。 例如,您可以傳送 OAuth 2.0 令牌:Authorization: Bearer eyJraWQiOiIyMDIwMDEyNTE2MzMiLCJhbGciOiJSUzI1NiJ9.eyJpYW1faWQiOiJJ
  5. 設定您的寄件者詳細資訊

    1. 寄件者中,輸入您要使用者從中接收電子郵件的電子郵件位址。

    2. 寄件者名稱中,輸入您要與「寄件者」電子郵件相關聯的名稱。

    3. 回覆中,輸入您要在其中接收任何電子郵件回覆的電子郵件位址。

  6. 按一下 測試,以使用測試電子郵件來嘗試您的配置。

  7. 按一下儲存以啟用您的組態。

使用 API 來配置自訂提供者

您可以使用 Cloud Directory 管理 API 來配置自訂電子郵件寄件者。

  1. 設定可以監聽 POST 請求的延伸點。 端點必須能夠:

    • 讀取來自 App ID的有效負載。
    • 從自訂提供者傳送電子郵件。
    • 選擇性地,協力廠商未以任何方式變更 App ID 所傳回的 JSON 有效負載 驗證。 會傳回格式化為 {"jws": "jws-format-string"} 的字串,其中包含您的租戶 ID、JWS 記號的發出者、傳送訊息時的時間戳記、唯一交易 ID,以及包含寄件者詳細資料及電子郵件內文內容的實際訊息資訊。

    您的延伸點可能與以下範例相似:

    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 instance tenant ID
       const tenantId = '<tenantID>';
    
       // Send request to App ID'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};
    }
    
  2. /management/v4/<tenantID>/config/cloud_directory/email_dispatcher 發出 PUT 請求,提供您的 webhook URL。 您可以選擇提供授權資訊。 支援的授權類型包括:Basic authorizationconstant 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>"
          }
       }
       }'
    
  3. 測試電子郵件分派器,驗證配置已正確設定。 使用 測試 API 觸發要求至您設定的自訂電子郵件寄件者。

電子郵件範本

將訊息傳送給使用者時,您可以使用下列範本的任何組合。 或者,您可以編輯範本來自訂訊息。

除了下列訊息類型外,您也可以利用 MFA 範本

若要進行進一步的自訂作業,您可以在訊息中使用參數。 查看下表,瞭解您可以在所有訊息類型中使用的參數。

您可以在向使用者發送的訊息中使用的參數
參數 說明
%{display.logo} 顯示您為「登入小組件」配置的影像。
%{user.displayName} 顯示使用者選擇要在與應用程式互動時使用的畫面名稱。
%{user.email} 顯示使用者的已登錄電子郵件位址。
%{user.username} 鑑別方法設為使用者名稱及密碼時,會顯示使用者的指定使用者名稱。
%{user.firstName} 顯示使用者的指定名字。
%{user.formattedName} 顯示使用者的完整名稱。
%{user.lastName} 顯示使用者的指定暱稱。

電子郵件:歡迎使用

當使用者註冊您的應用程式時,您可能想要傳送一則訊息給他們,來歡迎他們使用您的應用程式。

  1. 移至服務儀表板的 雲端目錄 > 電子郵件範本 > 歡迎電子郵件 索引標籤。

  2. 歡迎使用電子郵件設為已啟用

  3. 自訂訊息的內容。 您可以使用控制台新增參數和插入圖片。 若要變更訊息的 語言,您可以使用 API 來設定語言。 但是,您必須對訊息的內容和轉換負責。 請查看下表,以瞭解您可以在此訊息中使用的表格清單,以及您可以傳送的所有其他訊息。 如果使用者未提供參數所取回的資訊,則它會出現空白。

  4. 按一下儲存

電子郵件:驗證

當使用者透過其電子郵件來註冊您的應用程式時,您可以傳送電子郵件給他們,要求他們確認其身分。 透過要求驗證,您可以限制可以登入您應用程式之偽造帳戶的數目。 您可以限制應用程式的存取,直到使用者已驗證其電子郵件,或是使用它作為管理您為哪些使用者建立設定檔的方法。

透過 App ID 儀表板或建立使用者 API 手動新增的使用者,不會自動收到此電子郵件。

  1. 移至服務儀表板的 雲端目錄 > 電子郵件範本 > 電子郵件驗證 索引標籤。

  2. 電子郵件驗證設為已啟用

  3. 容許使用者登入您的應用程式,而不需要先驗證其電子郵件位址設為。 若設為「是」,使用者可以在註冊之後但在驗證其電子郵件位址之前,與您的應用程式互動。 預設值為「否」。

  4. 自訂訊息的內容。 您可以使用控制台新增參數和插入圖片。 若要變更訊息的 語言,您可以使用 API 來設定語言。 但是,您必須對訊息的內容和轉換負責。 請參閱下表,以查看您可以在訊息中使用的不同參數。 如果使用者未提供參數所取回的資訊,則它會出現空白。

    您可以在與驗證相關的訊息中使用的參數
    參數 說明
    %{linkExpiration.hours} 顯示鏈結有效的時數。
    %{linkExpiration.minutes} 顯示鏈結有效的分鐘數。
    %{verify.code} 顯示一次性驗證 URL。
    %{verify.link} 顯示您已在設定中指定的動作 URL。

    您也可以使用歡迎使用訊息區段中所列出的訊息參數。

  5. 定義動作 URL 的有效期限。 URL 有效期限是使用者在驗證鏈結到期之前必須完成動作的時間量(分鐘)。 此設定也會影響重設密碼鏈結有效的時間量。

  6. 輸入當使用者在感謝您頁面 URL 方框中驗證其電子郵件之後您想要顯示的頁面 URL。 如果您選擇將此欄位保留空白,則會顯示 App ID 預設頁面。

  7. 按一下儲存

電子郵件:重設密碼

當使用者與您的應用程式互動時,他們可能會忘記其密碼,或需要更新它。 您可以自訂對其要求的電子郵件回應。 當使用者要求變更其密碼時,密碼會保持不變,直到他們按一下此電子郵件中的鏈結為止。

  1. 移至服務儀表板的 Cloud Directory > Email templates > Reset password(重設密碼 )索引標籤。

  2. 忘記密碼電子郵件設為已啟用

  3. 自訂訊息的內容。 您可以使用控制台新增參數和插入圖片。 若要變更訊息的 語言,您可以使用 API 來設定語言。 但是,您必須對訊息的內容和轉換負責。 請參閱下表,以查看您可以在訊息中使用的不同參數。 如果使用者未提供參數所取回的資訊,則它會出現空白。

    您可以在與忘記密碼相關的訊息中使用的參數
    參數 說明
    %{linkExpiration.hours} 顯示鏈結有效的時數。
    %{linkExpiration.minutes} 顯示鏈結有效的分鐘數。
    %{resetPassword.code} 將一次性通行碼顯示為 URL 的一部分。 這表示每一個人員都將具有不同的通行碼。 範例: https://us-south.appid.cloud.ibm.com/wfm/verify/6574839563478
    %{resetPassword.link} 顯示使用者按一下即可重設其密碼的鏈結。

    您也可以使用歡迎使用訊息區段中所列出的訊息參數。

  4. 定義動作 URL 的有效期限。 URL 有效期限是使用者在驗證鏈結到期之前必須完成動作的時間量(分鐘)。 此設定也會影響重設密碼鏈結有效的時間量。

  5. 輸入當使用者在重設密碼頁面 URL 方框中驗證其電子郵件之後您想要顯示的頁面 URL。 如果您選擇將此欄位保留空白,則會顯示 App ID 預設頁面。

  6. 按一下儲存

電子郵件:密碼變更

更新使用者的密碼時,您可以通知使用者。 如果他們並未要求變更其密碼,則此通知會很有用。 他們可以採取適當的步驟來重新保護帳戶安全。

  1. 移至服務儀表板的 雲端目錄 > 電子郵件範本 > 密碼變更 索引標籤。

  2. 密碼變更電子郵件設為已啟用

  3. 自訂訊息的內容。 您可以使用控制台新增參數和插入圖片。 若要變更訊息的 語言,您可以使用 API 來設定語言。 但是,您必須對訊息的內容和轉換負責。 請參閱下表,以查看您可以在訊息中使用的不同參數。 如果使用者未提供參數所取回的資訊,則它會出現空白。

    您可以在與變更密碼相關的訊息中使用的參數
    參數 說明
    %{passwordChangeInfo.time} 顯示新密碼生效的時間。
    %{passwordChangeInfo.ipAddress} 顯示從中要求密碼變更的 IP 位址。

    您也可以使用歡迎使用訊息區段中所列出的訊息參數。

  4. 按一下儲存

支援的語言

您可以使用 語言管理 API 設定用戶通訊的語言。 不過,預設只能使用英文。 您負責轉換訊息。 使用 API 設定配置之後,就會更新 GUI,讓您能夠變更範本文字。

支援的語言
代碼 語言 地區
af-ZA 南非荷蘭文 南非
sq-AL 阿爾巴尼亞文 阿爾巴尼亞
am-ET 阿姆哈拉文 衣索比亞
ar-DZ 阿拉伯文 阿爾及利亞
ar-BH 阿拉伯文 巴林
ar-EG 阿拉伯文 埃及
ar-IQ 阿拉伯文 伊拉克
ar-JO 阿拉伯文 約旦
ar-KW 阿拉伯文 科威特
ar-LB 阿拉伯文 黎巴嫩
ar-LY 阿拉伯文 利比亞
ar-MR 阿拉伯文 茅利塔尼亞
ar-MA 阿拉伯文 摩洛哥
ar-OM 阿拉伯文 阿曼
ar-QA 阿拉伯文 卡達
ar-SA 阿拉伯文 沙烏地阿拉伯
ar-SY 阿拉伯文 敘利亞
ar-YE 阿拉伯文 突尼西亞
ar-AE 阿拉伯文 阿拉伯聯合大公國
ar-YE 阿拉伯文 葉門
hy-AM 亞美尼亞文 亞美尼亞
as-IN 阿薩姆文 印度
az-AZ 亞塞拜然文 亞塞拜然
eu-ES 巴斯克文 西班牙
be-BY 白俄羅斯文 白俄羅斯
bn-BD 孟加拉文 孟加拉
be-BY 白俄羅斯文 白俄羅斯
bn-BD 孟加拉文 孟加拉
bn-IN 孟加拉文 印度
bs-Latn-BA 波士尼亞文 波士尼亞
bg-BG 保加利亞文 保加利亞
my-MM 緬甸文 緬甸
ca-ES 加泰蘭文 西班牙
zh-Hans-CN 簡體中文 中國
zh-Hans-SG 簡體中文 新加坡
zh-Hant-HK 繁體中文 中國香港特別行政區
zh-Hant-MO 繁體中文 中國澳門特別行政區
zh-Hant-TW 繁體中文 台灣
hr-HR 克羅埃西亞文 克羅埃西亞共和國
cs-CZ 捷克文 捷克共和國
da-DK 丹麥文 丹麥
nl-BE 荷蘭文 比利時
nl-NL 荷蘭文 荷蘭
en-AU 英文 澳洲
eu-BE 英文 比利時
en-CM 英文 喀麥隆
eu-CA 英文 加拿大
en-GH 英文 迦納
eu-HK 英文 中國香港特別行政區
en-IN 英文 印度
en-IE 英文 愛爾蘭
en-KE 英文 肯亞
en-MU 英文 模里西斯
en-NZ 英文 紐西蘭
en-NG 英文 奈及利亞
en-PH 英文 菲律賓
en-SG 英文 新加坡
en-ZA 英文 南非
en-TZ 英文 坦尚尼亞
en-GB 英文 英國
en-US 英文 美國
en-ZM 英文 尚比亞
en 英文
et-EE 愛沙尼亞文 愛沙尼亞
fil-PH 菲律賓文 菲律賓
fi-FI 芬蘭文 芬蘭
fr-DZ 法文 阿爾及利亞
fr-CM 法文 喀麥隆
fr-CD 法文 剛果民主共和國
fr-BE 法文 比利時
fr-CA 法文 加拿大
fr-FR 法文 法國
fr-CI 法文 象牙海岸(象牙海岸共和國)
fr-LU 法文 盧森堡
fr-MR 法文 茅利塔尼亞
fr-MU 法文 模里西斯
fr-MA 法文 摩洛哥
fr-SN 法文 塞內加爾
fr-CH 法文 瑞士
fr-TN 法文 突尼西亞
gl-ES 加利西亞文 西班牙
lg-UG 干達文 烏干達
ka-GE 喬治亞文 喬治亞
de-AT 德文 奧地利
de-DE 德文 德國
de-LU 德文 盧森堡
de-CH 德文 瑞士
el-GR 希臘文 希臘
gu-IN 古吉拉特文 印度
ha-NG 豪薩文 奈及利亞
he-IL 希伯來文 以色列
hi-IN 北印度文 印度
hu-HU 匈牙利文 匈牙利
is-IS 冰島文 冰島
ig-NG 伊博文 奈及利亞
id-ID 印尼文 印尼
it-IT 義大利文 義大利
it-CH 義大利文 瑞士
ja-JP 日文 日本
kn-IN 坎那達文 印度
kk-KZ 哈薩克文 哈薩克
km-KH 高棉文 柬埔寨
rw-RW 金亞盧安文 盧安達
kok-IN 貢根文 印度
ko-KR 韓文 南韓
lo-LA 立陶宛文 立陶宛
lv-LV 拉脫維亞文 拉脫維亞
lt-LT 高棉文 柬埔寨
mk-MK 馬其頓文 馬其頓
ms-Latn-MY 馬來拉丁文 馬來西亞
ml-IN 馬來亞拉姆文 印度
mt-MT 馬爾他文 馬爾他
mr-IN 馬拉地文 印度
mn-Cyrl-MN 蒙古斯拉夫語 蒙古
ne-IN 尼泊爾文 印度
ne-NP 尼泊爾文 尼泊爾
nb-NO 巴克摩挪威文 挪威
nn-NO 新挪威文 挪威
or-IN 奧里亞文(歐迪亞文) 印度
om-ET 奧里亞文 衣索比亞
pl-PL 波蘭文 波蘭
pt-AO 葡萄牙文 安哥拉
pt-BR 葡萄牙文 巴西
pt-MO 葡萄牙文 中國澳門特別行政區
pt-MZ 葡萄牙文 莫三比克
pt-PT 葡萄牙文 葡萄牙
pa-IN 旁遮普文 印度
ro-RO 羅馬尼亞文 羅馬尼亞
ru-RU 俄文 俄羅斯
sr-Cyrl-RS 塞爾維亞斯拉夫語 塞爾維亞
sr-Latn-ME 塞爾維亞拉丁文 芒特尼格羅共和國
sr-Latn-RS 塞爾維亞拉丁文 塞爾維亞
si-LK 辛哈拉文 斯里蘭卡
sk-SK 斯洛伐克文 斯洛伐克
sl-SI 斯洛維尼亞文 斯洛維尼亞
es-AR 西班牙文 阿根廷
es-BO 西班牙文 玻利維亞
es-CL 西班牙文 智利
es-CO 西班牙文 哥倫比亞
es-CR 西班牙文 哥斯大黎加
es-DO 西班牙文 多明尼加共和國
es-EC 西班牙文 厄瓜多爾
es-SV 西班牙文 薩爾瓦多
es-GT 西班牙文 瓜地馬拉
es-HN 西班牙文 宏都拉斯
es-MX 西班牙文 墨西哥
es-NI 西班牙文 尼加拉瓜
es-PA 西班牙文 巴拿馬
es-PY 西班牙文 巴拉圭
es-PE 西班牙文 秘魯
es-PR 西班牙文 波多黎各
es-ES 西班牙文 西班牙
es-US 西班牙文 美國
es-UY 西班牙文 烏拉圭
es-VE 西班牙文 委內瑞拉
sw-KE 斯華西里文 肯亞
sw-TZ 斯華西里文 坦尚尼亞
sv-SE 瑞典文 瑞典
ta-IN 泰米爾文 印度
te-IN 泰盧固文 印度
th-TH 泰文 泰國
tr-TR 土耳其文 土耳其
uk-UA 烏克蘭文 烏克蘭
ur-IN 烏都文 印度
ur-PK 烏都文 巴基斯坦
uz-Cyrl-UZ 烏茲別克斯拉夫語 烏玆別克
uz-Latn-UZ 烏茲別克拉丁文 烏玆別克
vi-VN 越南文 越南
cy-GB 威爾斯文 英國
yo-NG 優魯巴文 奈及利亞
zu-ZA 祖魯 南非