แม่แบบอีเมล

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

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

Code

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

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

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 ที่ root จะไม่แทนที่ handlebars placeholder ใด ๆ
• หาก object application ที่ให้มาไม่มีฟิลด์ที่ต้องการหรือค่ากำหนดเป็น undefined placeholder จะถูกแทนที่ด้วยสตริงว่าง เช่น {{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 ฝั่ง client จะพิจารณาจาก header Accept-Language ใน request สำหรับ Management APIs (เช่น Organization Invitation) สามารถระบุภาษาที่ต้องการได้โดยใส่พารามิเตอร์ locale ในฟิลด์ messagePayload ของ request body
2. เมื่อพบภาษาที่ต้องการ Logto จะค้นหาแม่แบบอีเมลที่ตรงกับ languageTag และ templateType หากมีแม่แบบสำหรับภาษานั้นและประเภทแม่แบบนั้น Logto จะใช้แม่แบบนั้นในการสร้างอีเมล
3. หากไม่พบภาษาที่ต้องการ หรือไม่มีแม่แบบสำหรับภาษานั้นและประเภทแม่แบบนั้น Logto จะใช้ภาษาหลักของ tenant ที่ตั้งค่าไว้ใน Sign-in Experience ดู Localized languages สำหรับรายละเอียดการตั้งค่า
4. หากไม่พบแม่แบบที่ตรงกัน Logto จะใช้แม่แบบอีเมลเริ่มต้นที่กำหนดไว้ใน config ของตัวเชื่อมต่อ

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

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

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

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

• HTTP Email
• Postmark

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

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

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

คุณสามารถเพิ่ม endpoint ใหม่ในเว็บเซอร์วิสของคุณเองเพื่อส่งอีเมล แล้วใช้ 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

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

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