본문으로 건너뛰기

이메일 템플릿

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

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

이메일 템플릿 유형​

usageType시나리오Variables
SignIn사용자가 이메일을 사용하여 로그인하고 비밀번호 대신 인증 코드를 입력하여 인증합니다.code: string
application: ApplicationInfo
organization?: OrganizationInfo
Register사용자가 이메일을 사용하여 계정을 생성하고 Logto에서 이메일로 전송한 인증 코드를 입력하여 인증합니다.code: string
application: ApplicationInfo
organization?: OrganizationInfo
ForgotPassword사용자가 로그인 중 비밀번호를 잊어버린 경우, 이미 Logto와 인증된 이메일을 사용하여 본인 확인을 선택할 수 있습니다.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 유형에 대한 자세한 내용은 프로필을 확인하세요.
  • UserPermissionValidation 및 BindNewIdentifier 템플릿의 경우, user 변수는 필수입니다.
  • OrganizationInvitation 템플릿의 경우, inviter 변수는 선택 사항입니다. 조직 초대 요청에 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>

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

지원되는 이메일 커넥터:

제공자 측 이메일 템플릿 현지화​

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

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

자주 묻는 질문​

Logto에 템플릿이 구성되어 있지 않은 경우 타사 이메일 템플릿 서비스를 사용하는 방법은 무엇인가요?​

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

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

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

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

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

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