Modelos de email

Logto fornece diferentes modelos para personalizar o conteúdo de email, que são categorizados com base em seus casos de uso.

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

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

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

1. Personalizar modelos no Logto

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

2. Personalizar modelos na plataforma do provedor

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

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

   • Connector:
     • Logto Built-in Email Service
   • Capacidades:
     • ✅ Suporte nativo a variáveis
     • ❌ Modelos multilíngues (Em breve)
     • ❌ Modificações de modelo / UI desativadas

Tipos de modelos de email

usageType	Cenário	Variáveis
SignIn	Usuários fazem login usando seu email e verificam inserindo o código de verificação em vez de inserir uma senha.	code: string application: ApplicationInfo organization?: OrganizationInfo
Register	Usuários criam uma conta usando seu 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 sua senha durante o login, eles podem optar por verificar sua identidade usando o email primeiro para redefinir a senha.	code: string application: ApplicationInfo organization?: OrganizationInfo
Generic	Este modelo pode ser usado como uma opção de backup geral para vários cenários, incluindo testar configurações de conector, verificar ou vincular email após o login, e assim por diante.	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 aplicativo, pode haver algumas operações de alto risco ou operações com um nível de risco relativamente alto que requerem 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 código de verificação por email que os usuários recebem nessas situações.	code: string user: UserInfo application?: ApplicationInfo
BindNewIdentifier	Quando um usuário modifica seu perfil, ele 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

Variáveis de 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 de verificação.
• Um espaço reservado {{code}} precisa ser reservado no modelo. Ao enviar um código de verificação, um código gerado aleatoriamente substituirá esse espaço reservado antes de enviarmos o email para os usuários.

ApplicationInfo

As informações públicas do aplicativo cliente com o qual os usuários estão 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 de informações do aplicativo aninhados podem ser acessados nos modelos através da 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 espaço reservado do handlebars será ignorado e não será substituído.
• Se o objeto application fornecido não contiver os campos necessários ou o valor for indefinido, o espaço reservado do handlebars será substituído por uma string vazia. Por exemplo, {{application.foo.bar}} será substituído por ``.

OrganizationInfo

As informações públicas da organização com a qual os usuários estão 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. Disponível apenas 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;
};

• Verifique perfil 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. Disponível apenas 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 de usuário. Para criar uma interface de usuário 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 atuais.

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

Os usuários podem consultar este modelo e ajustá-lo de acordo com 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>Verify your email to sign in</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>Verify your email to sign in</h1>
          <p>
            We have received a sign in attempt with the following code. Please enter it in the page
            you opened to complete the sign in process.
          </p>
          <div class="verification-code">000000</div>
          <p style="color: #747778;">
            If you did not attempt to sign in but received this email, please ignore it. The code
            will remain active for 10 minutes.
          </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>:
        The better identity infrastructure for developers.
      </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;">
        Have questions or need help?
        <a href="{{mailToUrl}}" style="color: #A9ACAC; text-decoration: underline;">Contact us</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

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 para 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 modelo de assunto do email.
content	O modelo de conteúdo do email.
contentType	Alguns provedores de email podem renderizar modelos de email de forma diferente com base no tipo de conteúdo. (por exemplo, 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.

Uma vez que os modelos de email são 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 do lado do cliente e User Account APIs, a preferência de idioma é determinada pelo cabeçalho Accept-Language na solicitação. Para Management APIs (como Convite de Organização), você pode especificar a preferência de idioma incluindo um parâmetro locale no campo messagePayload do corpo da solicitaçã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 um modelo existir 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 nenhum modelo personalizado existir para o idioma e tipo de modelo detectados, o Logto usará o idioma padrão do locatário configurado na Experiência de Login. Verifique 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.

Connectors de email suportados:

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

Localização de modelos de email do lado do provedor

Para desenvolvedores que usam os connectors de email que têm modelos de email gerenciados pelo provedor:

• HTTP Email
• Postmark

O idioma preferido do usuário será passado para o 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, em seguida, usar o conector HTTP email do Logto para chamar o endpoint que você mantém.

Isso permite que você lide com a lógica de modelo de email em seu próprio servidor.

Existe uma maneira 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 manipulador de webhook.

O conector de email do Logto apenas fornece notificações por 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 através de Webhooks.

Recursos relacionados

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