이메일 템플릿
Logto는 이메일 콘텐츠를 맞춤화할 수 있는 다양한 템플릿을 제공하며, 사용 사례에 따라 분류되어 있습니다.
서로 다른 시나리오에서 서로 다른 템플릿을 사용하는 것이 강력히 권장됩니다. 그렇지 않으면 사용자가 현재 작업과 일치하지 않는 이메일 콘텐츠를 받아 혼란을 초래할 수 있습니다. 설정되지 않은 템플릿이 누락된 경우, 해당 템플릿에 의존하는 플로우 오류가 발생하여 비즈니스의 정상적인 진행에 영향을 줄 수 있습니다.
이메일 템플릿 맞춤화 옵션
Logto는 이메일 템플릿 관리를 위해 세 가지 뚜렷한 방식을 제공합니다:
-
Logto에서 템플릿 맞춤화
- 커넥터:
- 기능:
- ✅ 다양한 변수를 템플릿에 유연하게 삽입 가능
- ✅ Management API를 통해 다국어 맞춤 템플릿 생성 가능
- ✅ Logto 내에서 템플릿 전체 편집 가능
-
프로바이더 플랫폼에서 템플릿 맞춤화
- 커넥터:
- 기능:
- ✅ 변수 값을 프로바이더 플랫폼으로 전달 가능
- ✅ 현지화를 위해
locale
파라미터를 프로바이더 플랫폼으로 전달 가능 - ✅ 프로바이더 대시보드에서 템플릿 전체 편집 가능 (Logto Management API 사용)
-
기본 제공 템플릿 (맞춤화 불가)
- 커넥터:
- 기능:
- ✅ 기본 변수 지원
- ❌ 다국어 템플릿 (곧 지원 예정)
- ❌ 템플릿 / 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
타입에 대한 자세한 내용은 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>
그런 다음 위의 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는 다음 우선순위에 따라 사용자의 언어 선호도에 맞는 이메일 템플릿을 자동으로 선택합니다:
- 클라이언트 측 Experience API 및 User Account API의 경우, 언어 선호도는 요청의
Accept-Language
헤더로 결정됩니다. Management API(예: 조직 초대)의 경우, 요청 본문의messagePayload
필드에locale
파라미터를 포함하여 언어 선호도를 지정할 수 있습니다. - 언어 선호도가 감지되면, Logto는
languageTag
와templateType
필드를 사용해 일치하는 맞춤 이메일 템플릿을 찾습니다. 지정된 언어 및 템플릿 유형에 대한 템플릿이 존재하면 해당 템플릿을 사용해 이메일을 렌더링합니다. - 언어 선호도가 감지되지 않거나, 감지된 언어 및 템플릿 유형에 대한 맞춤 템플릿이 없는 경우, Logto는 Sign-in Experience에서 구성된 테넌트의 기본 언어를 사용합니다. 구성 방법은 다국어 지원을 참고하세요.
- 일치하는 템플릿이 없으면, Logto는 커넥터 구성에 정의된 기본 이메일 템플릿을 사용합니다.
지원 이메일 커넥터:
프로바이더 측 이메일 템플릿 현지화
이메일 템플릿이 프로바이더에서 관리되는 이메일 커넥터를 사용하는 개발자의 경우:
사용자 선호 언어는 템플릿 페이로드의 locale
파라미터로 프로바이더에 전달됩니다. 프로바이더 콘솔에서 다양한 언어별 템플릿을 생성하고, locale
파라미터로 언어 선호도를 지정할 수 있습니다.
자주 묻는 질문
Logto에 템플릿이 설정되어 있지 않은 경우, 타사 이메일 템플릿 서비스를 사용하는 방법은?
자체 웹 서비스에 이메일 전송용 엔드포인트를 추가한 후, Logto HTTP 이메일 커넥터를 사용해 직접 관리하는 엔드포인트를 호출할 수 있습니다.
이렇게 하면 이메일 템플릿 로직을 자체 서버에서 처리할 수 있습니다.
Logto 이메일을 사용해 사용자에게 맞춤 "환영 이메일"을 보낼 수 있나요?
Webhook 기능을 제공합니다. Logto Webhook이 전송하는 User.Created
이벤트를 수신하는 자체 API 엔드포인트를 구현하고, Webhook 핸들러 내에서 맞춤 환영 이메일을 전송하는 로직을 추가할 수 있습니다.
Logto 이메일 커넥터는 인증 (Authentication) 플로우와 관련된 이벤트에 대해서만 이메일 알림을 제공합니다. 환영 이메일은 비즈니스 요구 사항이므로 이메일 커넥터에서 기본적으로 지원하지 않지만, Webhook을 통해 구현할 수 있습니다.
관련 리소스
인증 이메일 전달률을 극대화하여 사용자 접근을 보장하세요