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 o 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 seu 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 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 pelo usuário nessas situações.	code: string user: UserInfo application?: ApplicationInfo
BindNewIdentifier	Quando um usuário modifica seu perfil, pode vincular um endereço de email à sua conta atual. Nesse 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 email MFA 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 email MFA está habilitado, este modelo é usado para configurar o código de verificação por email para MFA. Os usuários recebem esse código ao vincular ou configurar o email como fator MFA em sua 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.

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 consultar este 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, por favor ignore-o. 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 o 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 de email personalizados para diferentes idiomas e tipos de modelo para fornecer 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 modelo de email.
content	O conteúdo do modelo de 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 de email.
replyTo	O endereço de email que receberá respostas ao email. 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.

Depois que os modelos de email forem criados, o Logto selecionará automaticamente o modelo de email apropriado com base na preferência de idioma do usuário, usando a seguinte ordem de prioridade:

1. Para Experience APIs e User Account APIs do lado do cliente, a preferência de idioma é determinada pelo cabeçalho Accept-Language na requisição. Para Management APIs (como Convite para Organização), você pode especificar a preferência de idioma incluindo um parâmetro locale no campo messagePayload do corpo da requisição.
2. Quando uma preferência de idioma é detectada, o Logto procura um modelo de email personalizado correspondente usando os campos languageTag e templateType. Se existir um modelo para o idioma e tipo de modelo especificados, o Logto usará esse modelo para renderizar o email.
3. Se nenhuma preferência de idioma for detectada, ou se não existir um modelo personalizado para o idioma e tipo de modelo detectados, o Logto usará o idioma padrão do tenant configurado na Experiência de Login. Veja Idiomas localizados para detalhes de configuração.
4. Se nenhum modelo correspondente for encontrado, o Logto usará o modelo de email 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 usam 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.

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