メールテンプレート
Logto では、メール内容をカスタマイズするためのさまざまなテンプレートが提供されており、用途ごとに分類されています。
異なるシナリオで異なるテンプレートを使用することを強く推奨します。そうしないと、ユーザーが現在の操作と一致しないメール内容を受け取り、混乱を招く可能性があります。未設定のテンプレートがある場合、そのテンプレートに依存するフローでエラーが発生し、ビジネスの正常な進行に影響を与えることがあります。
メールテンプレートのカスタマイズオプション
Logto では、メールテンプレート管理のために 3 つの異なるアプローチを提供しています：
-
Logto 内でテンプレートをカスタマイズ
- コネクター:
- 機能:
- ✅ テンプレート内に多様な変数を柔軟に挿入可能
- ✅ Management API を通じてカスタム多言語テンプレートを作成可能
- ✅ Logto 内でテンプレートを完全編集可能
-
プロバイダーのプラットフォームでテンプレートをカスタマイズ
- コネクター:
- 機能:
- ✅ 変数をプロバイダープラットフォームへ渡すことが可能
- ✅
localeパラメーターをプロバイダープラットフォームへ渡してローカライズ可能 - ✅ プロバイダーのダッシュボードでテンプレートを完全編集可能（Logto Management API を利用）
-
プリセットテンプレート（カスタマイズ不可）
- コネクター:
- 機能:
- ✅ ネイティブ変数サポート
- ❌ 多言語テンプレート (近日対応予定)
- ❌ テンプレート / UI の変更不可
メールテンプレートの種類
| usageType | シナリオ | 変数 |
|---|---|---|
| SignIn | ユーザーが メールでサインイン し、パスワードの代わりに認証コードを入力して認証します。 | code: string application: ApplicationInfoorganization?: OrganizationInfo |
| Register | ユーザーが メールでアカウントを作成 し、Logto から送信された認証コードを入力して認証します。 | code: string application: ApplicationInfoorganization?: OrganizationInfo |
| ForgotPassword | ログイン時にパスワードを忘れた場合、まずメールで本人確認を行い パスワードをリセット できます。 | code: string application: ApplicationInfoorganization?: OrganizationInfo |
| Generic | このテンプレートは、コネクター設定のテストや サインイン後のメール認証や連携 など、さまざまなシナリオの汎用バックアップオプションとして利用できます。 | code: string |
| OrganizationInvitation | このテンプレートを使用して、ユーザーに 組織への招待リンクを送信 できます。 | link: string organization: OrganizationInfoinviter?: UserInfo |
| UserPermissionValidation | アプリ利用中に、銀行振込やリソース削除、会員解約など 追加のユーザー認証が必要な高リスク操作 の際に、このテンプレートでユーザーが受け取るメール認証コードの内容を定義できます。 | code: string user: UserInfoapplication?: ApplicationInfo |
| BindNewIdentifier | ユーザーがプロフィールを変更する際に 現在のアカウントにメールアドレスを連携 する場合、このテンプレートで認証メールの内容をカスタマイズできます。 | code: string user: UserInfoapplication?: ApplicationInfo |
| MfaVerification | メール MFA が有効な場合、多要素認証プロセス中にユーザーへ認証コードを送信する際にこのテンプレートが使用されます。 | code: string application: ApplicationInfoorganization?: OrganizationInfo |
| BindMfa | メール MFA が有効な場合、MFA 用のメール認証コードを設定する際にこのテンプレートが使用されます。ユーザーがメールアドレスを MFA 要素として連携または設定する際に認証コードを受け取ります。 | code: string user: UserInfoapplication?: 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 を参照してください。UserPermissionValidationおよびBindNewIdentifierテンプレートではuser変数は必須です。OrganizationInvitationテンプレートではinviter変数はオプションです。組織招待リクエストでinviterIdが指定されている場合のみ利用可能です。
メールテンプレートの例
提供されているメールテンプレートのコード例をカスタマイズの出発点として利用できます。例えば、次のようなユーザーインターフェースを作成できます：
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 | 一部のメールプロバイダーは contentType によってテンプレートのレンダリング方法が異なります（例：Sendgrid、Mailgun）。このフィールドでメールテンプレートのタイプを指定します。 |
| replyTo | メールの返信先アドレス。このフィールドがサポートされているかはメールプロバイダーにご確認ください。 |
| sendFrom | メール送信者の表示名。このフィールドがサポートされているかはメールプロバイダーにご確認ください。 |
メールテンプレート作成後、Logto はユーザーの言語設定に基づき、以下の優先順位で適切なメールテンプレートを自動選択します：
- クライアントサイドの 体験 API および ユーザーアカウント API では、リクエストの
Accept-Languageヘッダーで言語設定が決まります。Management API（例：組織招待）では、リクエストボディのmessagePayloadフィールドにlocaleパラメーターを含めて言語設定を指定できます。 - 言語設定が検出された場合、Logto は
languageTagとtemplateTypeで一致するカスタムメールテンプレートを検索します。該当テンプレートが存在すれば、それを使用してメールをレンダリングします。 - 言語設定が検出されない、または該当するカスタムテンプレートが存在しない場合、Sign-in Experience で設定されたテナントのデフォルト言語が使用されます。設定方法は ローカライズ言語 を参照してください。
- 一致するテンプレートが見つからない場合、コネクター設定で定義されたデフォルトのメールテンプレートが使用されます。
対応メールコネクター:
プロバイダー側のメールテンプレートローカライズ
プロバイダー側でメールテンプレートを管理するメールコネクターを利用する場合：
ユーザーの希望言語はテンプレートペイロードの locale パラメーターとしてプロバイダーに渡されます。プロバイダーのコンソールで言語ごとに複数のテンプレートを作成し、locale パラメーターで言語設定を指定できます。
よくある質問
Logto でテンプレートを設定していない場合、サードパーティのメールテンプレートサービスを利用するには？
独自の Web サービスにメール送信用のエンドポイントを追加し、Logto HTTP メールコネクター を使ってそのエンドポイントを呼び出すことができます。
これにより、メールテンプレートのロジックを自分のサーバー側で自由に管理できます。
Logto のメールでカスタマイズした「ウェルカムメール」をユーザーに送信する方法は？
Webhook 機能を提供しています。Logto Webhook から送信される User.Created イベントを受信する独自の API エンドポイントを実装し、Webhook ハンドラー内でカスタマイズしたウェルカムメール送信ロジックを追加できます。
Logto のメールコネクターは認証フロー関連イベントの通知のみを提供します。ウェルカムメールはビジネス要件であり、メールコネクターでは標準対応していませんが、Webhook を利用することで実現可能です。
関連リソース
認証メールの到達率を最大化し、ユーザーアクセスを保証する