이메일 템플릿

Logto는 이메일 콘텐츠를 사용자 정의할 수 있는 다양한 템플릿을 제공하며, 이는 사용 사례에 따라 분류됩니다.

다른 시나리오에서 다른 템플릿을 사용하는 것이 강력히 권장됩니다. 그렇지 않으면 사용자가 현재 작업과 일치하지 않는 이메일 콘텐츠를 받을 수 있어 혼란을 초래할 수 있습니다. 구성되지 않은 누락된 템플릿이 있는 경우, 해당 템플릿에 의존하는 흐름 오류가 발생하여 비즈니스의 정상적인 진행에 영향을 미칠 수 있습니다.

이메일 템플릿 사용자 정의 옵션

Logto는 이메일 템플릿 관리를 위한 세 가지 방법을 제공합니다:

1. Logto에서 템플릿 사용자 정의

   • 커넥터:
     • SMTP
     • SendGrid
     • Mailgun
     • AWS Direct Mail
     • Aliyun Direct Mail
   • 기능:
     • ✅ 다양한 변수를 템플릿에 유연하게 삽입
     • ✅ Management API를 통해 사용자 정의 다국어 템플릿 생성
     • ✅ Logto 내에서 전체 템플릿 편집

2. 제공자 플랫폼에서 템플릿 사용자 정의

   • 커넥터:
     • Postmark
     • HTTP Email
   • 기능:
     • ✅ 제공자 플랫폼에 변수 전달
     • ✅ 로컬라이제이션을 위한 locale 매개변수를 제공자 플랫폼에 전달
     • ✅ 제공자의 대시보드 내에서 전체 템플릿 편집 (Logto Management API 사용)

3. 사전 구축된 템플릿 (사용자 정의 불가)

   • 커넥터:
     • Logto 내장 이메일 서비스
   • 기능:
     • ✅ 기본 변수 지원
     • ❌ 다국어 템플릿 (곧 제공 예정)
     • ❌ 템플릿/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

이메일 템플릿 변수

코드

사용자가 인증 과정을 완료하기 위해 입력해야 하는 인증 코드입니다. 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.name}}은 구성에서 실제 애플리케이션 이름으로 대체됩니다.
• 루트 application 변수가 제공되지 않으면, 핸들바 자리 표시자는 무시되고 대체되지 않습니다.
• 제공된 application 객체에 필요한 필드가 없거나 값이 정의되지 않은 경우, 핸들바 자리 표시자는 빈 문자열로 대체됩니다. 예: {{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 유형에 대한 자세한 내용은 프로필을 확인하세요.
• 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>Verify your email to sign in</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>Verify your email to sign in</h1>
          <p>
            We have received a sign in attempt with the following code. Please enter it in the page
            you opened to complete the sign in process.
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            If you did not attempt to sign in but received this email, please ignore it. The code
            will remain active for 10 minutes.
          </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>:
        The better identity infrastructure for developers.
      </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;">
        Have questions or need help?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;">Contact us</a>
      </p>
    </div>
  </body>
</html>

위의 HTML 코드를 이스케이프하여 SendGrid 커넥터를 사용하는 경우 다음과 같이 구성의 "Template" 필드에 추가할 수 있습니다:

{
  "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	이메일 발신자의 이름 별칭입니다. 이 필드가 지원되는지 이메일 제공자에게 확인하세요.

이메일 템플릿이 생성되면, Logto는 사용자의 언어 선호도에 따라 적절한 이메일 템플릿을 자동으로 선택합니다. 우선 순위는 다음과 같습니다:

1. 클라이언트 측 Experience API 및 User Account API의 경우, 언어 선호도는 요청의 Accept-Language 헤더에 의해 결정됩니다. Management API (예: Organization Invitation)의 경우, 요청 본문의 messagePayload 필드에 locale 매개변수를 포함하여 언어 선호도를 지정할 수 있습니다.
2. 언어 선호도가 감지되면, Logto는 languageTag 및 templateType 필드를 사용하여 일치하는 사용자 정의 이메일 템플릿을 찾습니다. 지정된 언어 및 템플릿 유형에 대한 템플릿이 존재하면, Logto는 해당 템플릿을 사용하여 이메일을 렌더링합니다.
3. 언어 선호도가 감지되지 않거나, 감지된 언어 및 템플릿 유형에 대한 사용자 정의 템플릿이 없는 경우, Logto는 Sign-in Experience에 구성된 테넌트의 기본 언어를 사용합니다. 구성 세부 사항은 Localized languages를 확인하세요.
4. 일치하는 템플릿을 찾을 수 없는 경우, Logto는 커넥터 구성에 정의된 기본 이메일 템플릿을 사용합니다.

지원되는 이메일 커넥터:

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

제공자 측 이메일 템플릿 로컬라이제이션

이메일 템플릿이 제공자에 의해 관리되는 이메일 커넥터를 사용하는 개발자를 위해:

• HTTP Email
• Postmark

사용자 선호 언어는 템플릿 페이로드의 locale 매개변수를 사용하여 제공자에게 전달됩니다. 제공자의 콘솔에서 다양한 언어에 대한 여러 템플릿을 생성하고 locale 매개변수를 사용하여 언어 선호도를 지정할 수 있습니다.

자주 묻는 질문

Logto에 템플릿이 구성되지 않은 경우 타사 이메일 템플릿 서비스를 사용하는 방법은 무엇입니까?

이메일을 보내기 위해 자체 웹 서비스에 새 엔드포인트를 추가한 다음, Logto HTTP 이메일 커넥터를 사용하여 유지 관리하는 엔드포인트를 호출할 수 있습니다.

이를 통해 이메일 템플릿 로직을 자체 서버에서 처리할 수 있습니다.

Logto 이메일을 사용하여 사용자에게 맞춤형 "환영 이메일"을 보낼 수 있는 방법이 있습니까?

우리는 Webhook 기능을 제공합니다. Logto Webhook이 보낸 User.Created 이벤트를 수신할 API 엔드포인트를 구현하고, 웹훅 핸들러 내에서 맞춤형 환영 이메일을 보내는 로직을 추가할 수 있습니다.

Logto 이메일 커넥터는 인증 흐름과 관련된 이벤트에 대한 이메일 알림만 제공합니다. 환영 이메일은 비즈니스 요구 사항이며 이메일 커넥터에서 기본적으로 지원되지 않지만, 이 기능은 Webhook을 통해 구현할 수 있습니다.

관련 리소스

사용자 접근을 보장하기 위한 인증 이메일 전달 최대화