이메일 템플릿

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
MfaVerification	이메일 MFA가 활성화된 경우, 다단계 인증 (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.name}}은 구성에서 실제 애플리케이션 이름으로 대체됩니다.
• 루트 application 변수가 제공되지 않은 경우, handlebars 플레이스홀더는 무시되고 대체되지 않습니다.
• 제공된 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 타입에 대한 자세한 내용은 프로필을 참고하세요.
• UserPermissionValidation, BindNewIdentifier 템플릿에서는 user 변수가 필수입니다.
• OrganizationInvitation 템플릿에서는 inviter 변수가 선택 사항입니다. 조직 초대 요청에 inviterId가 제공된 경우에만 사용 가능합니다.

UI Locales

현재 상호작용을 시작한 OIDC 인증 요청에서 제공된 원본 ui_locales 값입니다.

• 타입: string (OIDC 명세에 따른 BCP 47 언어 태그의 공백 구분 리스트), 예: "fr-CA fr en".
• 사용 가능 조건: 현재 로그인 상호작용이 ui_locales로 시작된 경우에만 존재합니다. 제공되지 않은 경우 이 변수는 생략됩니다.
• 일반적인 사용: 이메일 내용 또는 제목에 포함하여 사용자가 요청한 UI 언어를 기록하거나 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>

위의 HTML 코드를 이스케이프 처리한 후, 아래와 같이 커넥터의 "Template" 필드에 추가할 수 있습니다 (SendGrid 커넥터 사용 예시):

{
  "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. OIDC 인증 요청에 ui_locales가 포함된 경우, Logto는 테넌트의 언어 라이브러리에서 지원하는 ui_locales의 첫 번째 태그를 선택합니다. 자세한 내용은 ui_locales를 참고하세요.
2. 그렇지 않은 경우, 클라이언트 측 Experience API 및 User Account API에서는 Accept-Language 헤더를 사용합니다. Management API (예: 조직 초대)에서는 messagePayload의 locale 필드로 언어를 지정할 수 있습니다.
3. 둘 다 제공되지 않은 경우, Logto는 로그인 경험에서 구성된 테넌트의 기본 언어를 사용합니다. 구성 방법은 현지화 언어를 참고하세요.

템플릿 선택:

4. 결정된 언어로, Logto는 languageTag와 templateType이 일치하는 맞춤 이메일 템플릿을 찾습니다. 있으면 해당 템플릿을 사용합니다.
5. 일치하는 맞춤 템플릿이 없으면, 커넥터 구성에 정의된 기본 이메일 템플릿을 사용합니다.

지원 이메일 커넥터:

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

프로바이더 측 이메일 템플릿 현지화

이메일 템플릿이 프로바이더에서 관리되는 커넥터를 사용하는 개발자의 경우:

• HTTP Email
• Postmark

사용자 선호 언어는 템플릿 페이로드의 locale 파라미터로 프로바이더에 전달됩니다. 프로바이더 콘솔에서 언어별로 여러 템플릿을 생성하고, locale 파라미터로 언어 선호도를 지정할 수 있습니다.

노트:

인증 요청에 ui_locales가 있는 경우, 템플릿 컨텍스트에서 locale과 uiLocales 변수를 모두 사용할 수 있습니다. uiLocales 변수에는 인증 요청의 원본 ui_locales 값이, locale 변수에는 ui_locales에서 지원되는 첫 번째 태그를 기준으로 결정된 값이 들어갑니다. ui_locales가 제공되지 않은 경우, locale은 표준 결정 규칙(예: Accept-Language, 그 다음 기본 언어)을 따릅니다.

자주 묻는 질문

Logto에 템플릿을 구성하지 않은 경우, 타사 이메일 템플릿 서비스를 어떻게 사용할 수 있나요?

자체 웹 서비스에 이메일 발송용 엔드포인트를 추가한 후, Logto HTTP 이메일 커넥터를 사용하여 직접 관리하는 엔드포인트를 호출할 수 있습니다.

이렇게 하면 이메일 템플릿 로직을 자체 서버에서 처리할 수 있습니다.

Logto 이메일을 사용하여 사용자에게 맞춤 "환영 이메일"을 보낼 수 있나요?

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

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

관련 리소스

인증 이메일 도달률을 극대화하여 사용자 접근을 보장하세요