แม่แบบอีเมล

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

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

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

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

1. ปรับแต่งแม่แบบใน Logto

   • ตัวเชื่อมต่อ (Connectors):
     • SMTP
     • SendGrid
     • Mailgun
     • AWS Direct Mail
     • Aliyun Direct Mail
   • ความสามารถ:
     • ✅ แทรกตัวแปรหลากหลายลงในแม่แบบได้อย่างยืดหยุ่น
     • ✅ สร้างแม่แบบหลายภาษาแบบกำหนดเองผ่าน Management APIs
     • ✅ แก้ไขแม่แบบได้เต็มรูปแบบภายใน Logto

2. ปรับแต่งแม่แบบในแพลตฟอร์มผู้ให้บริการ

   • ตัวเชื่อมต่อ (Connectors):
     • Postmark
     • HTTP Email
   • ความสามารถ:
     • ✅ ส่งตัวแปรไปยังแพลตฟอร์มผู้ให้บริการ
     • ✅ ส่งพารามิเตอร์ locale ไปยังแพลตฟอร์มผู้ให้บริการเพื่อการแปลภาษา
     • ✅ แก้ไขแม่แบบได้เต็มรูปแบบในแดชบอร์ดของผู้ให้บริการ (ใช้ Logto Management APIs)

3. แม่แบบสำเร็จรูป (ไม่สามารถปรับแต่งได้)

   • ตัวเชื่อมต่อ (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	เมื่อเปิดใช้งาน email MFA แม่แบบนี้จะใช้ส่งรหัสยืนยันให้ผู้ใช้ระหว่างกระบวนการยืนยันตัวตนหลายปัจจัย	code: string application: ApplicationInfo organization?: OrganizationInfo
BindMfa	เมื่อเปิดใช้งาน email 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 ของคุณ เพื่อสร้างอินเทอร์เฟซผู้ใช้คล้ายกับตัวอย่างต่อไปนี้:

เนื่องจากแม่แบบอีเมลที่ใช้ในแต่ละสถานการณ์ของ 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 จะเลือกแม่แบบที่เหมาะสมโดยอัตโนมัติตามภาษาที่ผู้ใช้ต้องการ โดยใช้ลำดับความสำคัญดังนี้:

1. สำหรับฝั่งไคลเอนต์ Experience APIs และ User Account APIs จะพิจารณาจาก header Accept-Language ใน request สำหรับ Management APIs (เช่น Organization Invitation) สามารถระบุภาษาที่ต้องการได้โดยใส่พารามิเตอร์ locale ในฟิลด์ messagePayload ของ request body
2. เมื่อพบภาษาที่ต้องการ Logto จะค้นหาแม่แบบอีเมลที่ตรงกันโดยใช้ languageTag และ templateType หากมีแม่แบบสำหรับภาษานั้นและประเภทแม่แบบนั้น Logto จะใช้แม่แบบนั้นในการสร้างอีเมล
3. หากไม่พบภาษาที่ต้องการ หรือไม่มีแม่แบบสำหรับภาษานั้นและประเภทแม่แบบนั้น Logto จะใช้ภาษาหลักของ tenant ที่ตั้งค่าไว้ใน Sign-in Experience ดู การตั้งค่าภาษา สำหรับรายละเอียด
4. หากไม่พบแม่แบบที่ตรงกัน Logto จะใช้แม่แบบอีเมลเริ่มต้นที่กำหนดไว้ใน config ของตัวเชื่อมต่อ

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

• Aliyun Direct Mail
• Amazon Direct Mail
• Mailgun
• SendGrid
• SMTP

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

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

• HTTP Email
• Postmark

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

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

จะใช้บริการแม่แบบอีเมลของบุคคลที่สามได้อย่างไร หากไม่ได้ตั้งค่าแม่แบบใน 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 เป็นความต้องการทางธุรกิจและไม่ได้รองรับโดยตรงในตัวเชื่อมต่ออีเมล แต่สามารถทำได้ผ่าน Webhooks

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

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