メインコンテンツまでスキップ

メールテンプレート

Logto では、メール内容をカスタマイズするためのさまざまなテンプレートが用意されており、用途ごとに分類されています。

異なるシナリオで異なるテンプレートを使用することを強く推奨します。そうしないと、ユーザーが現在の操作と一致しないメール内容を受け取り、混乱を招く可能性があります。設定されていないテンプレートが不足している場合、そのテンプレートに依存するフローエラーが発生し、ビジネスの正常な進行に影響を与えることがあります。

メールテンプレートのカスタマイズオプション​

Logto では、メールテンプレート管理のために 3 つの異なるアプローチを提供しています：

  1. Logto 内でテンプレートをカスタマイズ

    • コネクター:
    • 機能:
      • ✅ テンプレート内に多様な変数を柔軟に挿入可能
      • ✅ Management API を通じてカスタム多言語テンプレートを作成可能
      • ✅ Logto 内でテンプレートを完全編集可能

  2. プロバイダー側プラットフォームでテンプレートをカスタマイズ

    • コネクター:
    • 機能:
      • ✅ 変数をプロバイダープラットフォームへ渡すことが可能
      • ✅ locale パラメーターをプロバイダープラットフォームへ渡してローカライズ対応
      • ✅ プロバイダーのダッシュボードでテンプレートを完全編集可能（Logto Management API を利用）

  3. プリビルトテンプレート（カスタマイズ不可）

    • コネクター:
    • 機能:
      • ✅ ネイティブ変数サポート
      • ❌ 多言語テンプレート (近日対応予定)
      • ❌ テンプレート / UI の変更不可

メールテンプレートの種類​

usageTypeシナリオ変数
SignInユーザーが メールでサインイン し、パスワードの代わりに認証コードを入力して認証 (Authentication) する場合。code: string
application: ApplicationInfo
organization?: OrganizationInfo
Registerユーザーが メールでアカウントを作成 し、Logto から送信された認証コードを入力して認証 (Authentication) する場合。code: string
application: ApplicationInfo
organization?: OrganizationInfo
ForgotPasswordログイン時にパスワードを忘れた場合、まずメールで本人確認を行い パスワードをリセット する場合。code: string
application: ApplicationInfo
organization?: OrganizationInfo
Genericこのテンプレートは、コネクター設定のテストや サインイン後のメール認証や連携 など、さまざまなシナリオの汎用バックアップオプションとして利用できます。code: string
OrganizationInvitationこのテンプレートを使用して、ユーザーに 組織への招待リンク を送信します。link: string
organization: OrganizationInfo
inviter?: UserInfo
UserPermissionValidationアプリ利用中に、銀行振込やリソース削除、会員解約など 追加のユーザー認証 (Authentication) が必要な高リスク操作 の際に、このテンプレートで認証コードメールの内容を定義できます。code: string
user: UserInfo
application?: ApplicationInfo
BindNewIdentifierユーザーがプロフィールを変更する際に メールアドレスを現在のアカウントに連携 する場合、このテンプレートで認証メールの内容をカスタマイズできます。code: string
user: UserInfo
application?: ApplicationInfo
MfaVerificationメール MFA が有効な場合、多要素認証プロセス中にユーザーへ認証コードを送信する際にこのテンプレートが使用されます。code: string
application: ApplicationInfo
organization?: OrganizationInfo
BindMfaメール MFA が有効な場合、MFA 用メール認証コードの設定時にこのテンプレートが使用されます。ユーザーがメールアドレスを MFA 要素として連携・設定する際に認証コードを受け取ります。code: string
user: UserInfo
application?: ApplicationInfo

メールテンプレートの変数​

Code​

ユーザーが認証 (Authentication) プロセスを完了するために入力する必要がある認証コードです。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 オブジェクトに必要なフィールドが含まれていない、または値が未定義の場合、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 Locales​

現在のインタラクションを開始した OIDC 認証 (Authentication) リクエストで提供された元の 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一部のメールプロバイダーは content type によってテンプレートのレンダリング方法が異なります（例：Sendgrid、Mailgun）。このフィールドでメールテンプレートの content type を指定できます。
replyToメールの返信先アドレス。このフィールドがサポートされているかはメールプロバイダーにご確認ください。
sendFromメール送信者の名前エイリアス。このフィールドがサポートされているかはメールプロバイダーにご確認ください。

メールテンプレート作成後、Logto はまずユーザーの言語設定を解決し、最適なテンプレートを自動選択します。

言語設定の解決順序：

  1. OIDC 認証 (Authentication) リクエストに ui_locales が含まれている場合、テナントの言語ライブラリでサポートされている最初のタグを選択します。詳細は ui_locales を参照してください。
  2. それ以外の場合、クライアントサイドの 体験 API や ユーザーアカウント API では Accept-Language ヘッダーを使用します。Management API（組織招待 など）では messagePayload の locale フィールドで言語指定が可能です。
  3. いずれも指定されていない場合、Sign-in 体験で設定されたテナントのデフォルト言語が使用されます。設定方法は ローカライズ言語 を参照してください。

テンプレート選択：

  1. 解決された言語で、languageTag と templateType に一致するカスタムメールテンプレートを検索し、存在すればそれを使用します。
  2. 一致するカスタムテンプレートがない場合、コネクター設定で定義されたデフォルトメールテンプレートが使用されます。

対応メールコネクター:

プロバイダー側メールテンプレートのローカライズ​

メールテンプレートがプロバイダー側で管理されているメールコネクターを利用する場合：

ユーザーの希望言語はテンプレートペイロードの locale パラメーターとしてプロバイダーに渡されます。プロバイダーのコンソールで言語ごとに複数のテンプレートを作成し、locale パラメーターで言語指定が可能です。

注記:

認証 (Authentication) リクエストに ui_locales が含まれている場合、テンプレートコンテキストで locale と uiLocales の両方の変数が利用可能です。 uiLocales 変数には認証 (Authentication) リクエストの元の ui_locales 値が入り、locale 変数は ui_locales から解決された最初のサポートタグに基づいて決定されます。ui_locales が指定されていない場合、locale は標準の解決ルール（例：Accept-Language、次にデフォルト言語）に従います。

よくある質問​

Logto でテンプレートを設定していない場合、サードパーティのメールテンプレートサービスを利用するには？​

独自の Web サービスにメール送信用の新しいエンドポイントを追加し、Logto HTTP メールコネクター でそのエンドポイントを呼び出すことができます。

これにより、メールテンプレートのロジックを自分のサーバー側で自由に管理できます。

Logto のメールでカスタマイズした「ウェルカムメール」をユーザーに送信する方法は？​

Webhook 機能を提供しています。Logto Webhook から送信される User.Created イベントを受信する独自の API エンドポイントを実装し、Webhook ハンドラー内でカスタムウェルカムメール送信ロジックを追加できます。

Logto のメールコネクターは認証 (Authentication) フロー関連イベントの通知のみを提供します。ウェルカムメールはビジネス要件であり、メールコネクターでネイティブにサポートされていませんが、Webhook を利用することで実現可能です。

認証メールの到達率を最大化し、ユーザーアクセスを保証する