Modelos de email

O Logto fornece diferentes modelos para personalizar o conteúdo dos emails, que são categorizados de acordo com seus casos de uso.

É altamente recomendado que você utilize modelos diferentes em cenários distintos. Caso contrário, os usuários podem receber conteúdos de email que não correspondem à operação atual, causando confusão. Se houver modelos ausentes que não estejam configurados, isso pode causar erros em fluxos que dependem desse modelo e afetar o desenvolvimento normal do negócio.

Opções de personalização de modelos de email

O Logto oferece três abordagens distintas para gerenciamento de modelos de email:

1. Personalizar modelos no Logto

   • Conectores:
     • SMTP
     • SendGrid
     • Mailgun
     • AWS Direct Mail
     • Aliyun Direct Mail
   • Capacidades:
     • ✅ Inserção flexível de diversas variáveis nos modelos
     • ✅ Criação de modelos personalizados multilíngues via Management APIs
     • ✅ Edição completa dos modelos dentro do Logto

2. Personalizar modelos na plataforma do provedor

   • Conectores:
     • Postmark
     • HTTP Email
   • Capacidades:
     • ✅ Passar variáveis para a plataforma do provedor
     • ✅ Passar o parâmetro locale para a plataforma do provedor para localização
     • ✅ Edição completa dos modelos no painel do provedor (Use Logto Management APIs)

3. Modelos pré-construídos (não personalizáveis)

   • Conector:
     • Serviço de Email Integrado do Logto
   • Capacidades:
     • ✅ Suporte nativo a variáveis
     • ❌ Modelos multilíngues (Em breve)
     • ❌ Modificações de modelo/UI desabilitadas

Tipos de modelos de email

usageType	Cenário	Variáveis
SignIn	Usuários fazem login usando o email e verificam inserindo um código de verificação em vez de uma senha.	code: string application: ApplicationInfo organization?: OrganizationInfo
Register	Usuários criam uma conta usando o email e a verificam inserindo um código de verificação enviado pelo Logto para o email.	code: string application: ApplicationInfo organization?: OrganizationInfo
ForgotPassword	Se os usuários esquecerem a senha durante o login, podem optar por verificar a identidade usando o email primeiro para redefinir a senha.	code: string application: ApplicationInfo organization?: OrganizationInfo
Generic	Este modelo pode ser usado como opção geral de backup para vários cenários, incluindo teste de configurações de conectores, verificação ou vinculação de email após login, entre outros.	code: string
OrganizationInvitation	Use este modelo para enviar aos usuários um link de convite para ingressar na organização.	link: string organization: OrganizationInfo inviter?: UserInfo
UserPermissionValidation	Durante o uso do app, pode haver operações de alto risco ou operações com nível de risco relativamente alto que exigem verificação adicional do usuário, como transferências bancárias, exclusão de recursos em uso e cancelamento de assinaturas. O modelo UserPermissionValidation pode ser usado para definir o conteúdo do email de verificação recebido nestas situações.	code: string user: UserInfo application?: ApplicationInfo
BindNewIdentifier	Quando um usuário modifica seu perfil, pode vincular um endereço de email à conta atual. Neste caso, o modelo BindNewIdentifier pode ser usado para personalizar o conteúdo do email de verificação.	code: string user: UserInfo application?: ApplicationInfo
MfaVerification	Quando MFA por email está habilitado, este modelo é usado para enviar códigos de verificação aos usuários durante o processo de autenticação multifatorial.	code: string application: ApplicationInfo organization?: OrganizationInfo
BindMfa	Quando MFA por email está habilitado, este modelo é usado para configurar o código de verificação por email para MFA. Os usuários recebem este código ao vincular ou configurar o email como fator MFA para a conta.	code: string user: UserInfo application?: ApplicationInfo

Variáveis dos modelos de email

Code

O código de verificação que os usuários precisam inserir para concluir o processo de verificação. Disponível nos modelos SignIn, Register, ForgotPassword, Generic, UserPermissionValidation e BindNewIdentifier.

• Os códigos de verificação expiram em 10 minutos. Atualmente não suportamos a personalização do tempo de expiração do código.
• Um placeholder {{code}} precisa ser reservado no modelo. Ao enviar um código de verificação, um código gerado aleatoriamente substituirá esse placeholder antes de enviarmos o email ao usuário.

ApplicationInfo

As informações públicas do aplicativo cliente com o qual o usuário está interagindo. Disponível nos modelos SignIn, Register, ForgotPassword, UserPermissionValidation e BindNewIdentifier.

type ApplicationInfo = {
  id: string;
  name: string;
  displayName?: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

• Todos os campos aninhados de informações do aplicativo podem ser acessados nos modelos usando notação de ponto. Por exemplo, {{application.name}} será substituído pelo nome real do aplicativo da sua configuração.
• Se a variável raiz application não for fornecida, o placeholder handlebars será ignorado e não será substituído.
• Se o objeto application fornecido não contiver os campos necessários ou o valor estiver indefinido, o placeholder handlebars será substituído por uma string vazia. Ex: {{application.foo.bar}} será substituído por ``.

OrganizationInfo

As informações públicas da organização com a qual o usuário está interagindo.

type OrganizationInfo = {
  id: string;
  name: string;
  branding?: {
    logoUrl?: string;
    darkLogoUrl?: string;
    favicon?: string;
    darkFavicon?: string;
  };
};

• Para os modelos SignIn, Register e ForgotPassword, a variável organization é opcional. Só está disponível quando o parâmetro organization_id está presente na solicitação de autorização. Veja Personalização específica da organização para mais detalhes.
• Para o modelo OrganizationInvitation, a variável organization é obrigatória.

UserInfo

As informações públicas do usuário para quem o email é enviado. Disponível nos modelos UserPermissionValidation, BindNewIdentifier e OrganizationInvitation.

type UserInfo = {
  id: string;
  name?: string;
  username?: string;
  primaryEmail?: string;
  primaryPhone?: string;
  avatar?: string;
  profile?: Profile;
};

• Consulte profile para mais detalhes sobre o tipo Profile.
• A variável user é obrigatória para os modelos UserPermissionValidation e BindNewIdentifier.
• A variável inviter é opcional para o modelo OrganizationInvitation. Só está disponível quando o inviterId é fornecido na solicitação de convite da organização.

UI Locales

O valor original de ui_locales fornecido na solicitação de autenticação OIDC que iniciou a interação atual.

• Tipo: string (lista separada por espaço de tags de idioma BCP 47, conforme especificação OIDC), por exemplo: "fr-CA fr en".
• Disponibilidade: Presente quando a interação de login atual foi iniciada com ui_locales. Se não for fornecido, esta variável é omitida.
• Uso típico: Incluir no conteúdo ou assunto do email para registrar os idiomas de UI solicitados pelo usuário para suporte a i18n ou auditoria, ex: Idiomas solicitados: {{uiLocales}}.

Exemplos de modelos de email

Você pode usar os exemplos de código de modelo de email fornecidos como ponto de partida para personalizar sua interface. Para criar uma interface semelhante à seguinte:

Como os modelos de email usados em diferentes cenários do Logto são muito semelhantes, com a única diferença sendo a descrição do cenário e operação atual.

Não mostramos o código HTML de todos os modelos em detalhes aqui. Em vez disso, usamos apenas o cenário de login como exemplo. Outros cenários, como cadastro e esqueci a senha, são muito semelhantes ao exemplo a seguir.

Os usuários podem se basear neste modelo e ajustar conforme sua situação real.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Verifique seu email para fazer login</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>Verifique seu email para fazer login</h1>
          <p>
            Recebemos uma tentativa de login com o seguinte código. Por favor, insira-o na página
            que você abriu para concluir o processo de login.
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            Se você não tentou fazer login mas recebeu este email, apenas ignore. O código
            permanecerá ativo por 10 minutos.
          </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>: A
        melhor infraestrutura de identidade para desenvolvedores.
      </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;">
        Tem dúvidas ou precisa de ajuda?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;">Fale conosco</a>
      </p>
    </div>
  </body>
</html>

Você pode então escapar o código HTML acima e adicioná-lo ao campo "Template" do conector nas configurações da seguinte forma (supondo uso do conector SendGrid):

{
  "subject": "<sign-in-template-subject>",
  "content": "<table cellpadding=\"0\" cellspacing=\"0\" ...",
  "usageType": "SignIn",
  "type": "text/html"
}

Localização de modelos de email

Modelos de email personalizados para diferentes idiomas

O Logto suporta a criação de modelos de email personalizados para diferentes idiomas via Management API. Você pode criar modelos personalizados para diferentes idiomas e tipos de modelo para oferecer uma experiência localizada aos seus usuários.

type EmailTemplate = {
  languageTag: string;
  templateType: TemplateType;
  details: {
    subject: string;
    content: string;
    contentType?: 'text/html' | 'text/plain';
    replyTo?: string;
    sendFrom?: string;
  };
};

Campo	Descrição
subject	O assunto do email.
content	O conteúdo do email.
contentType	Alguns provedores de email podem renderizar modelos de email de forma diferente com base no tipo de conteúdo. (ex: Sendgrid, Mailgun). Use este campo para especificar o tipo de conteúdo do modelo.
replyTo	O endereço de email que receberá as respostas. Verifique com seu provedor de email se este campo é suportado.
sendFrom	O nome do remetente do email. Verifique com seu provedor de email se este campo é suportado.

Uma vez criados os modelos de email, o Logto selecionará automaticamente o modelo apropriado resolvendo primeiro a preferência de idioma do usuário e, em seguida, escolhendo o modelo mais adequado.

A preferência de idioma é resolvida na seguinte ordem:

1. Se a solicitação de autenticação OIDC incluir ui_locales, o Logto seleciona a primeira tag em ui_locales que seja suportada pela biblioteca de idiomas do tenant. Veja ui_locales para detalhes.
2. Caso contrário, para Experience APIs e User Account APIs do lado do cliente, o Logto usa o cabeçalho Accept-Language. Para Management APIs (como Convite de Organização), você pode especificar o idioma via campo locale em messagePayload.
3. Se nenhum for fornecido, o Logto utiliza o idioma padrão do tenant configurado na Experiência de Login. Veja Idiomas localizados para detalhes de configuração.

Seleção do modelo:

4. Com o idioma resolvido, o Logto procura um modelo de email personalizado correspondente usando languageTag e templateType. Se encontrado, esse modelo é utilizado.
5. Se não houver modelo personalizado correspondente, o Logto utiliza o modelo padrão definido na configuração do conector.

Conectores de email suportados:

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

Localização de modelos de email no provedor

Para desenvolvedores que utilizam conectores de email cujos modelos são gerenciados pelo provedor:

• HTTP Email
• Postmark

O idioma preferido do usuário será passado ao provedor usando o parâmetro locale no payload do modelo. Você pode criar vários modelos para diferentes idiomas no console do provedor e usar o parâmetro locale para especificar a preferência de idioma.

nota:

Quando ui_locales está presente na solicitação de autenticação, tanto as variáveis locale quanto uiLocales estarão disponíveis no contexto do modelo. A variável uiLocales contém o valor original de ui_locales da solicitação de autenticação, enquanto a variável locale é determinada com base na primeira tag suportada resolvida de ui_locales. Se ui_locales não for fornecido, locale segue as regras padrão de resolução (ex: Accept-Language, depois idioma padrão).

Perguntas frequentes

Como usar serviços de modelo de email de terceiros se os modelos não estiverem configurados no Logto?

Você pode adicionar um novo endpoint ao seu próprio serviço web para enviar emails e então usar o conector HTTP email do Logto para chamar o endpoint que você mantém.

Isso permite que você gerencie a lógica dos modelos de email no seu próprio servidor.

Existe uma forma de usar o email do Logto para enviar aos nossos usuários um "email de boas-vindas" personalizado?

Oferecemos a funcionalidade de Webhook. Você pode implementar seu próprio endpoint de API para receber o evento User.Created enviado pelo Webhook do Logto e adicionar lógica para enviar um email de boas-vindas personalizado dentro do handler do webhook.

O conector de email do Logto fornece apenas notificações de email para eventos relacionados ao fluxo de autenticação. Emails de boas-vindas são um requisito de negócio e não são suportados nativamente pelo conector de email, mas essa funcionalidade pode ser alcançada via Webhooks.

Recursos relacionados

Maximize a entrega de emails de verificação para garantir o acesso do usuário