แม่แบบอีเมล

Logto มีแม่แบบสำหรับปรับแต่งเนื้อหาอีเมลในแต่ละกรณีการใช้งานที่แตกต่างกัน

ขอแนะนำอย่างยิ่งให้ใช้แม่แบบที่แตกต่างกันในแต่ละสถานการณ์ มิฉะนั้นผู้ใช้อาจได้รับเนื้อหาอีเมลที่ไม่ตรงกับการดำเนินการปัจจุบัน ซึ่งอาจทำให้เกิดความสับสน หากมีแม่แบบที่ขาดหายและไม่ได้ตั้งค่า อาจทำให้เกิดข้อผิดพลาดใน flow ที่ต้องพึ่งพาแม่แบบนั้น และส่งผลกระทบต่อการดำเนินธุรกิจตามปกติ

ตัวเลือกการปรับแต่งแม่แบบอีเมล

Logto มี 3 วิธีหลักสำหรับการจัดการแม่แบบอีเมล:

ปรับแต่งแม่แบบใน Logto
- ตัวเชื่อมต่อ (Connectors):
- ความสามารถ:
  - ✅ แทรกตัวแปรหลากหลายลงในแม่แบบได้อย่างยืดหยุ่น
  - ✅ สร้างแม่แบบหลายภาษาแบบกำหนดเองผ่าน Management APIs
  - ✅ แก้ไขแม่แบบได้เต็มรูปแบบภายใน Logto
ปรับแต่งแม่แบบในแพลตฟอร์มผู้ให้บริการ
- ตัวเชื่อมต่อ (Connectors):
  - Postmark
  - HTTP Email
- ความสามารถ:
  - ✅ ส่งผ่านตัวแปรไปยังแพลตฟอร์มผู้ให้บริการ
  - ✅ ส่งผ่านพารามิเตอร์ locale ไปยังแพลตฟอร์มผู้ให้บริการเพื่อรองรับหลายภาษา
  - ✅ แก้ไขแม่แบบได้เต็มรูปแบบในแดชบอร์ดของผู้ให้บริการ (ใช้ Logto Management APIs)
แม่แบบสำเร็จรูป (ไม่สามารถปรับแต่งได้)
- ตัวเชื่อมต่อ (Connector):
  - Logto Built-in Email Service
- ความสามารถ:
  - ✅ รองรับตัวแปรพื้นฐาน
  - ❌ แม่แบบหลายภาษา (เร็ว ๆ นี้)
  - ❌ ไม่สามารถแก้ไขแม่แบบ / UI ได้

ประเภทของแม่แบบอีเมล

usageType	สถานการณ์การใช้งาน	ตัวแปรที่ใช้ได้
SignIn	ผู้ใช้ ลงชื่อเข้าใช้ด้วยอีเมล และยืนยันโดยกรอกรหัสยืนยันแทนการกรอกรหัสผ่าน	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
Register	ผู้ใช้ สร้างบัญชีด้วยอีเมล และยืนยันโดยกรอกรหัสยืนยันที่ Logto ส่งไปยังอีเมลของตน	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
ForgotPassword	หากผู้ใช้ลืมรหัสผ่านขณะเข้าสู่ระบบ สามารถเลือกยืนยันตัวตนด้วยอีเมลก่อนเพื่อ รีเซ็ตรหัสผ่าน	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
Generic	แม่แบบนี้ใช้เป็นตัวเลือกสำรองทั่วไปสำหรับหลายสถานการณ์ เช่น ทดสอบการตั้งค่าตัวเชื่อมต่อ, ยืนยันหรือเชื่อมโยงอีเมลหลังลงชื่อเข้าใช้ เป็นต้น	code: string
OrganizationInvitation	ใช้แม่แบบนี้เพื่อ ส่งลิงก์เชิญผู้ใช้ ให้เข้าร่วมองค์กร	link: string organization: `OrganizationInfo` inviter?: `UserInfo`
UserPermissionValidation	ระหว่างการใช้งานแอป อาจมีบางการดำเนินการที่มีความเสี่ยงสูงหรือมีระดับความเสี่ยงค่อนข้างสูงที่ ต้องการการยืนยันตัวตนเพิ่มเติม เช่น โอนเงิน ลบทรัพยากรที่ใช้งานอยู่ หรือยกเลิกสมาชิก แม่แบบ `UserPermissionValidation` ใช้กำหนดเนื้อหาอีเมลรหัสยืนยันที่ผู้ใช้จะได้รับในสถานการณ์เหล่านี้	code: string user: `UserInfo` application?: `ApplicationInfo`
BindNewIdentifier	เมื่อผู้ใช้แก้ไขโปรไฟล์ อาจ เชื่อมโยงอีเมลใหม่กับบัญชีปัจจุบัน ในกรณีนี้สามารถใช้แม่แบบ `BindNewIdentifier` เพื่อปรับแต่งเนื้อหาอีเมลยืนยันได้	code: string user: `UserInfo` application?: `ApplicationInfo`
MfaVerification	เมื่อเปิดใช้งาน อีเมล MFA แม่แบบนี้ใช้ส่งรหัสยืนยันให้ผู้ใช้ระหว่างกระบวนการยืนยันตัวตนหลายปัจจัย	code: string application: `ApplicationInfo` organization?: `OrganizationInfo`
BindMfa	เมื่อเปิดใช้งาน อีเมล MFA แม่แบบนี้ใช้สำหรับตั้งค่ารหัสยืนยันอีเมลสำหรับ MFA ผู้ใช้จะได้รับรหัสนี้เมื่อเชื่อมโยงหรือกำหนดค่าอีเมลเป็นปัจจัย MFA ให้กับบัญชีของตน	code: string user: `UserInfo` application?: `ApplicationInfo`

ตัวแปรในแม่แบบอีเมล

Code

รหัสยืนยันที่ผู้ใช้ต้องกรอกเพื่อดำเนินการยืนยันให้เสร็จสมบูรณ์ ใช้ได้ในแม่แบบ SignIn, Register, ForgotPassword, Generic, UserPermissionValidation และ BindNewIdentifier

รหัสยืนยันหมดอายุใน 10 นาที ขณะนี้ยังไม่รองรับการปรับแต่งระยะเวลาหมดอายุของรหัสยืนยัน
ต้องสำรองตำแหน่ง {{code}} ในแม่แบบ เมื่อส่งรหัสยืนยัน ระบบจะสุ่มรหัสและแทนที่ตำแหน่งนี้ก่อนส่งอีเมลถึงผู้ใช้

ApplicationInfo

ข้อมูลสาธารณะของแอปพลิเคชันที่ผู้ใช้กำลังโต้ตอบด้วย ใช้ได้ในแม่แบบ SignIn, Register, ForgotPassword, UserPermissionValidation และ BindNewIdentifier

type ApplicationInfo = {
  id: string;
  name: string;
  displayName?: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

สามารถเข้าถึงฟิลด์ย่อยทั้งหมดของ application info ในแม่แบบได้ด้วย dot notation เช่น {{application.name}} จะถูกแทนที่ด้วยชื่อแอปจริงจากการตั้งค่าของคุณ
หากไม่ได้ส่งตัวแปร application หลักมา ตัวแปร handlebars จะถูกละเว้นและไม่ถูกแทนที่
หาก object application ที่ส่งมาไม่มีฟิลด์ที่ต้องการหรือค่าเป็น undefined ตัวแปร handlebars จะถูกแทนที่ด้วยสตริงว่าง เช่น {{application.foo.bar}} จะถูกแทนที่ด้วย ``

OrganizationInfo

ข้อมูลสาธารณะขององค์กรที่ผู้ใช้กำลังโต้ตอบด้วย

type OrganizationInfo = {
  id: string;
  name: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

สำหรับแม่แบบ SignIn, Register และ ForgotPassword ตัวแปร organization เป็นตัวเลือก จะมีให้ใช้เมื่อมีพารามิเตอร์ organization_id ในคำขอการอนุญาต ดู การตั้งค่าแบรนด์เฉพาะองค์กร สำหรับรายละเอียดเพิ่มเติม
สำหรับแม่แบบ OrganizationInvitation ตัวแปร organization จำเป็นต้องมี

UserInfo

ข้อมูลสาธารณะของผู้ใช้ที่อีเมลถูกส่งถึง ใช้ได้ในแม่แบบ UserPermissionValidation, BindNewIdentifier และ OrganizationInvitation

type UserInfo = {
  id: string;
  name?: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  avatar?: string;
  profile?: Profile;
};

ดู profile สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับชนิด Profile
ตัวแปร user จำเป็นสำหรับแม่แบบ UserPermissionValidation และ BindNewIdentifier
ตัวแปร inviter เป็นตัวเลือกสำหรับแม่แบบ OrganizationInvitation จะมีให้ใช้เมื่อมี inviterId ในคำขอเชิญองค์กร

UI Locales

ค่าต้นฉบับของ ui_locales ที่ส่งมาในคำขอการยืนยันตัวตน OIDC ที่เริ่มต้นการโต้ตอบนี้

ชนิด: string (รายการ tag ภาษา BCP 47 คั่นด้วยช่องว่าง ตามสเปค OIDC) เช่น "fr-CA fr en"
การมีอยู่: จะมีเมื่อการโต้ตอบการลงชื่อเข้าใช้ปัจจุบันถูกเริ่มต้นด้วย ui_locales หากไม่ได้ส่งมาจะไม่มีตัวแปรนี้
ตัวอย่างการใช้งาน: ใส่ในเนื้อหาอีเมลหรือหัวเรื่องเพื่อบันทึกภาษาที่ผู้ใช้ร้องขอสำหรับการรองรับ i18n หรือการตรวจสอบ เช่น Requested languages: {{uiLocales}}

ตัวอย่างแม่แบบอีเมล

คุณสามารถใช้ตัวอย่างโค้ดแม่แบบอีเมลที่ให้ไว้เป็นจุดเริ่มต้นในการปรับแต่ง UI ของคุณ เพื่อสร้างอินเทอร์เฟซผู้ใช้คล้ายกับตัวอย่างด้านล่างนี้:

เนื่องจากแม่แบบอีเมลที่ใช้ในแต่ละสถานการณ์ของ Logto มีความคล้ายคลึงกันมาก โดยแตกต่างกันเพียงคำอธิบายสถานการณ์และการดำเนินการปัจจุบัน

เราจะไม่แสดงโค้ด HTML ของทุกแม่แบบโดยละเอียดที่นี่ แต่จะยกตัวอย่างเฉพาะกรณี ลงชื่อเข้าใช้ เท่านั้น กรณีอื่น ๆ เช่น สมัครสมาชิกหรือลืมรหัสผ่าน มีโครงสร้างคล้ายกันกับตัวอย่างนี้

ผู้ใช้สามารถอ้างอิงแม่แบบนี้และปรับแต่งตามสถานการณ์จริงของตน

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ยืนยันอีเมลของคุณเพื่อเข้าสู่ระบบ</title>
    <style>
      .auth-service-by:hover .mini-logo {
        display: none !important;
      }
      .auth-service-by:hover .mini-logo-color {
        display: block !important;
      }
      body {
        font-family:
          'SF Pro Text',
          -apple-system,
          system-ui,
          BlinkMacSystemFont,
          'Segoe UI',
          Roboto,
          Arial,
          sans-serif;
        -webkit-font-smoothing: antialiased;
        -moz-osx-font-smoothing: grayscale;
        font-smooth: always;
        background-color: #fff;
        color: #191c1d;
        max-width: 640px;
        padding: 32px 0;
        font-size: 14px;
        font-weight: 400;
        line-height: 20px;
      }
      h1 {
        font-size: 24px;
        font-weight: 700;
        line-height: 32px;
        margin-top: 32px;
      }
      .verification-code {
        margin: 20px 0;
        background: #eff1f1;
        border-radius: 12px;
        padding: 36px;
        font-size: 32px;
        font-weight: 600;
        line-height: 40px;
      }
      .footer {
        text-align: center;
        color: #a9acac;
        margin-top: 48px;
      }
    </style>
  </head>
  <body>
    <div style="max-width: 698px; border-radius: 16px; border: 1px solid #E0E3E3;">
      <div style="padding: 0 24px;">
        <center>
          <img src="{{logoUrl}}" alt="Logo" width="auto" height="40" />
          <h1>ยืนยันอีเมลของคุณเพื่อเข้าสู่ระบบ</h1>
          <p>
            เราได้รับความพยายามในการเข้าสู่ระบบโดยใช้รหัสต่อไปนี้
            กรุณากรอกรหัสนี้ในหน้าที่คุณเปิดไว้เพื่อดำเนินการเข้าสู่ระบบให้เสร็จสมบูรณ์
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            หากคุณไม่ได้พยายามเข้าสู่ระบบแต่ได้รับอีเมลนี้ กรุณาเพิกเฉย รหัสจะใช้งานได้ 10 นาที
          </p>
          <hr style="margin: 64px 0 24px; max-width: 420px;" />
          <p style="color: #747778; margin: 16px 0 0;">{{companyInfo}}</p>
        </center>
      </div>
    </div>
    <div class="footer">
      <hr />
      <p style="font-size: 14px; line-height: 20px; margin: 20px 0;">
        <a href="https://logto.io" style="color: #A9ACAC; text-decoration: underline;">Logto</a>:
        โครงสร้างพื้นฐานด้านเอกลักษณ์ที่ดีกว่าสำหรับนักพัฒนา
      </p>
      <table style="margin: 0 auto; width: auto; border-spacing: 0;">
        <tbody>
          <tr>
            <td style="vertical-align: middle;">
              <a href="{{discordServerUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{discordLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{githubUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{githubLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{twitterUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{twitterLogoUrl}}" style="width: 20px;" />
              </a>
            </td>
            <td style="vertical-align: middle;">
              <a href="{{mailToUrl}}" style="display: block; margin: 0 12px;">
                <img src="{{emailIconUrl}}" style="width: 20px;" />
              </a>
            </td>
          </tr>
        </tbody>
      </table>
      <p style="font-size: 12px; line-height: 16px;">
        © Silverhand, Inc., 2810 North Church Street, Wilmington, DE 19802
      </p>
      <p style="color: #A9ACAC; font-size: 12px; line-height: 16px;">
        มีคำถามหรือต้องการความช่วยเหลือ?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;">ติดต่อเรา</a>
      </p>
    </div>
  </body>
</html>

จากนั้นคุณสามารถ escape โค้ด HTML ข้างต้นและเพิ่มลงในฟิลด์ "Template" ของตัวเชื่อมต่อใน config ได้ดังนี้ (สมมติใช้ SendGrid connector):

{
  "subject": "<sign-in-template-subject>",
  "content": "<table cellpadding=\"0\" cellspacing=\"0\" ...",
  "usageType": "SignIn",
  "type": "text/html"
}

การแปลแม่แบบอีเมล

สร้างแม่แบบอีเมลหลายภาษาด้วยตนเอง

Logto รองรับการสร้างแม่แบบอีเมลหลายภาษาผ่าน Management API คุณสามารถสร้างแม่แบบอีเมลสำหรับแต่ละภาษาและแต่ละประเภทแม่แบบ เพื่อมอบประสบการณ์ที่ตรงกับภาษาของผู้ใช้

type EmailTemplate = {
  languageTag: string;
  templateType: TemplateType;
  details: {
    subject: string;
    content: string;
    contentType?: 'text/html' | 'text/plain';
    replyTo?: string;
    sendFrom?: string;
  };
};

ฟิลด์	คำอธิบาย
subject	แม่แบบหัวเรื่องของอีเมล
content	แม่แบบเนื้อหาอีเมล
contentType	ผู้ให้บริการอีเมลบางรายอาจแสดงผลแม่แบบอีเมลแตกต่างกันตามชนิดเนื้อหา (เช่น Sendgrid, Mailgun) ใช้ฟิลด์นี้เพื่อระบุชนิดเนื้อหาของแม่แบบอีเมล
replyTo	อีเมลที่จะรับการตอบกลับ ตรวจสอบกับผู้ให้บริการอีเมลของคุณว่ารองรับฟิลด์นี้หรือไม่
sendFrom	ชื่อผู้ส่งอีเมล (alias) ตรวจสอบกับผู้ให้บริการอีเมลของคุณว่ารองรับฟิลด์นี้หรือไม่

เมื่อสร้างแม่แบบอีเมลแล้ว Logto จะเลือกแม่แบบที่เหมาะสมโดยอัตโนมัติโดยอิงจากลำดับความชอบภาษาของผู้ใช้ แล้วเลือกแม่แบบที่ตรงที่สุด

ลำดับการเลือกภาษามีดังนี้:

หากคำขอการยืนยันตัวตน OIDC มี ui_locales Logto จะเลือก tag แรกใน ui_locales ที่รองรับโดยไลบรารีภาษา tenant ของคุณ ดู ui_locales สำหรับรายละเอียด
หากไม่ใช่ กรณี Experience APIs และ User Account APIs ฝั่ง client Logto จะใช้ header Accept-Language สำหรับ Management APIs (เช่น Organization Invitation) คุณสามารถระบุภาษาได้ผ่านฟิลด์ locale ใน messagePayload
หากไม่มีทั้งสองอย่าง Logto จะ fallback เป็นภาษาหลักของ tenant ที่ตั้งค่าไว้ใน Sign-in Experience ดู การตั้งค่าภาษา สำหรับรายละเอียด

การเลือกแม่แบบ:

เมื่อได้ภาษาที่ต้องการแล้ว Logto จะค้นหาแม่แบบอีเมลที่ตรงกับ languageTag และ templateType หากพบจะใช้แม่แบบนั้น
หากไม่พบแม่แบบที่ตรง Logto จะใช้แม่แบบอีเมลเริ่มต้นที่กำหนดไว้ใน config ของตัวเชื่อมต่อ

ตัวเชื่อมต่ออีเมลที่รองรับ:

การแปลแม่แบบอีเมลฝั่งผู้ให้บริการ

สำหรับนักพัฒนาที่ใช้ตัวเชื่อมต่ออีเมลที่จัดการแม่แบบอีเมลโดยผู้ให้บริการ:

ภาษาที่ผู้ใช้ต้องการจะถูกส่งไปยังผู้ให้บริการผ่านพารามิเตอร์ locale ใน payload ของแม่แบบ คุณสามารถสร้างแม่แบบหลายภาษาบนคอนโซลของผู้ให้บริการและใช้ locale เพื่อระบุภาษาที่ต้องการ

บันทึก:

เมื่อมี ui_locales ในคำขอการยืนยันตัวตน ตัวแปร locale และ uiLocales จะมีใน context ของแม่แบบ ตัวแปร uiLocales จะเก็บค่าต้นฉบับของ ui_locales จากคำขอ ส่วน locale จะถูกกำหนดจาก tag แรกที่รองรับใน ui_locales หากไม่มี ui_locales ตัวแปร locale จะใช้กฎการเลือกภาษาตามปกติ (เช่น Accept-Language แล้ว fallback เป็นภาษาหลัก)

คำถามที่พบบ่อย

จะใช้บริการแม่แบบอีเมลของบุคคลที่สามได้อย่างไร หากไม่ได้ตั้งค่าแม่แบบใน Logto?

คุณสามารถเพิ่ม endpoint ใหม่ใน web service ของคุณเองเพื่อส่งอีเมล แล้วใช้ Logto HTTP email connector เรียก endpoint ที่คุณดูแล

วิธีนี้ช่วยให้คุณจัดการตรรกะแม่แบบอีเมลบนเซิร์ฟเวอร์ของคุณเอง

มีวิธีใช้ Logto email เพื่อส่ง "Welcome email" แบบกำหนดเองให้ผู้ใช้ของเราหรือไม่?

เรามีฟีเจอร์ Webhook คุณสามารถสร้าง API endpoint ของคุณเองเพื่อรับ event User.Created ที่ส่งโดย Logto Webhook และเพิ่มตรรกะเพื่อส่ง welcome email แบบกำหนดเองใน handler ของ webhook

ตัวเชื่อมต่ออีเมลของ Logto ให้บริการแจ้งเตือนอีเมลเฉพาะเหตุการณ์ที่เกี่ยวข้องกับ flow การยืนยันตัวตนเท่านั้น Welcome email เป็นความต้องการทางธุรกิจและไม่ได้รองรับโดยตรงในตัวเชื่อมต่ออีเมล แต่สามารถทำได้ผ่าน Webhook

เพิ่มอัตราการส่งอีเมลยืนยันเพื่อรับประกันการเข้าถึงของผู้ใช้

ตัวเลือกการปรับแต่งแม่แบบอีเมล​

ประเภทของแม่แบบอีเมล​

ตัวแปรในแม่แบบอีเมล​

Code​

ApplicationInfo​

OrganizationInfo​

UserInfo​

UI Locales​

ตัวอย่างแม่แบบอีเมล​

การแปลแม่แบบอีเมล​

สร้างแม่แบบอีเมลหลายภาษาด้วยตนเอง​

การแปลแม่แบบอีเมลฝั่งผู้ให้บริการ​

คำถามที่พบบ่อย​

จะใช้บริการแม่แบบอีเมลของบุคคลที่สามได้อย่างไร หากไม่ได้ตั้งค่าแม่แบบใน Logto?​

มีวิธีใช้ Logto email เพื่อส่ง "Welcome email" แบบกำหนดเองให้ผู้ใช้ของเราหรือไม่?​

แหล่งข้อมูลที่เกี่ยวข้อง​