Better Auth

O Better Auth chama uma função sua toda vez que precisa mandar e-mail. A integração é essa função — não há adaptador, plugin nem configuração intermediária.

É o que a gente faz com a gente. O painel do Kourio autentica com Better Auth, e os e-mails de redefinição e verificação dele saem pelo nosso próprio transporte. Este guia é o nosso código de produção, com os nomes trocados.

Instalar

npm install @kourio/sdk better-auth

pnpm add @kourio/sdk better-auth

yarn add @kourio/sdk better-auth

.env

KOURIO_API_KEY=kou_live_...

A chave permite enviar em nome de todos os seus domínios verificados. Ela vive no servidor, nunca em código que chega ao navegador.

O mínimo que funciona

auth.ts

import { betterAuth } from 'better-auth';
import { Kourio } from '@kourio/sdk';

const kourio = new Kourio(process.env.KOURIO_API_KEY!);
const DE = 'Sua Empresa <conta@news.suaempresa.com.br>';

export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
    sendResetPassword: async ({ user, url }) => {
      await kourio.emails.send({
        from: DE,
        to: user.email,
        subject: 'Redefinir sua senha',
        html: `<p>Clique <a href="${url}">aqui</a> para redefinir sua senha. O link vale por 1 hora.</p>`,
        text: `Para redefinir sua senha, abra: ${url}\n\nO link vale por 1 hora.`,
      });
    },
  },
  emailVerification: {
    sendOnSignUp: true,
    sendVerificationEmail: async ({ user, url }) => {
      await kourio.emails.send({
        from: DE,
        to: user.email,
        subject: 'Confirme seu e-mail',
        html: `<p>Clique <a href="${url}">aqui</a> para confirmar seu endereço.</p>`,
        text: `Para confirmar seu endereço, abra: ${url}`,
      });
    },
  },
});

Um remetente só, em um lugar só

Depois do terceiro gancho, o mesmo bloco começa a ser copiado com uma vírgula diferente. Vale extrair antes disso:

mailer.ts

import { Kourio } from '@kourio/sdk';

const kourio = new Kourio(process.env.KOURIO_API_KEY!);

export async function enviarDeAutenticacao(input: {
  para: string;
  assunto: string;
  html: string;
  texto: string;
}) {
  try {
    await kourio.emails.send({
      from: 'Sua Empresa <conta@news.suaempresa.com.br>',
      to: input.para,
      subject: input.assunto,
      html: input.html,
      text: input.texto,
    });
  } catch (erro) {
    /*
     * A falha é registrada, não propagada.
     *
     * Se o envio derrubar a resposta, a mensagem de erro conta a quem pediu se aquele endereço
     * existe na sua base — e é assim que um formulário de "esqueci a senha" vira uma ferramenta
     * de enumeração de usuários. Responda igual nos dois casos.
     */
    console.error('[auth] falha ao enviar', { assunto: input.assunto, erro });
  }
}

Link mágico

import { magicLink } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    magicLink({
      sendMagicLink: async ({ email, url }) => {
        await enviarDeAutenticacao({
          para: email,
          assunto: 'Seu link de acesso',
          html: `<p>Clique <a href="${url}">aqui</a> para entrar. O link vale por 5 minutos e serve uma vez só.</p>`,
          texto: `Para entrar, abra: ${url}\n\nO link vale por 5 minutos e serve uma vez só.`,
        });
      },
    }),
  ],
});

Link mágico é senha. Diga o prazo na mensagem e mantenha-o curto. Um link de acesso que vale uma semana é uma senha permanente esquecida numa caixa de entrada.

Código de uma vez (OTP)

import { emailOTP } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    emailOTP({
      sendVerificationOTP: async ({ email, otp, type }) => {
        const assunto =
          type === 'sign-in' ? `${otp} é seu código de acesso` : `${otp} é seu código`;
        await enviarDeAutenticacao({
          para: email,
          assunto,
          html: `<p style="font-size:28px;font-weight:600;letter-spacing:4px">${otp}</p><p>Vale por 5 minutos.</p>`,
          texto: `Seu código: ${otp}\n\nVale por 5 minutos.`,
        });
      },
    }),
  ],
});

Ponha o código no assunto. Quem está esperando um código o lê na notificação, sem abrir a mensagem — e essa é a diferença entre alguns segundos e mais um passo no meio de um login.

Convite para organização

import { organization } from 'better-auth/plugins';

export const auth = betterAuth({
  plugins: [
    organization({
      sendInvitationEmail: async ({ email, inviter, organization: org, id }) => {
        const url = `https://app.suaempresa.com.br/aceitar-convite/${id}`;
        await enviarDeAutenticacao({
          para: email,
          assunto: `${inviter.user.name} convidou você para ${org.name}`,
          html: `<p>${inviter.user.name} convidou você para <strong>${org.name}</strong>.</p>
                 <p><a href="${url}">Aceitar convite</a></p>`,
          texto: `${inviter.user.name} convidou você para ${org.name}.\n\nAceite em: ${url}`,
        });
      },
    }),
  ],
});

Com template do Kourio

Se você quer a marca no e-mail sem escrever HTML de 2007, publique um template no painel e mande só as variáveis. O assunto e o remetente vêm dele:

await kourio.emails.send({
  templateId: 'redefinir-senha',   // o slug que você deu ao template
  to: user.email,
  variables: { nome: user.name ?? '', url },
});

Cada bloco de template é um contrato: dado esse conteúdo, o Kourio garante que sai certo no Outlook, no modo escuro e nos 600px de largura. Você escreve o texto; a marcação é problema nosso.

Três coisas que só aparecem em produção

Mande text junto do html — sempre

Mensagem só em HTML pontua pior em filtro de spam, e a redefinição de senha é justamente a que não pode cair na caixa errada. O campo text custa uma linha.

Não deixe a falha do envio derrubar a resposta

Se sendResetPassword lançar, o Better Auth propaga o erro para quem pediu — e a diferença entre “enviado” e “erro” conta a um atacante quais endereços existem na sua base. Registre a falha e responda igual nos dois casos.

Autenticação não é marketing

Deixe esses envios como TRANSACTIONAL, que é o padrão. A classe decide por qual reputação a mensagem sai, e as duas são medidas em separado justamente para que uma campanha ruim não impeça alguém de entrar na própria conta.

Quando não chega

Confira se o domínio está verificado

Nenhuma mensagem sai de um domínio sem SPF, DKIM e DMARC publicados. Veja Domínios.

Procure a mensagem pelo endereço

GET /v1/emails?search=… traz a linha do tempo: aceita, entregue, adiada, devolvida. É o que responde “chegou?” sem depender do seu log.

Veja se o endereço está suprimido

Um endereço que devolveu permanentemente para de receber — inclusive transacional. Veja Supressões.

Enviar

As duas formas de montar uma mensagem, o que conta na cota, e por que marketing sai por outro caminho.

Começar

Enviar

Saber o que aconteceu

Conta

Integrações

Instalar

O mínimo que funciona

Um remetente só, em um lugar só

Link mágico

Código de uma vez (OTP)

Convite para organização

Com template do Kourio

Três coisas que só aparecem em produção

Quando não chega

Enviar

​Instalar

​O mínimo que funciona

​Um remetente só, em um lugar só

​Link mágico

​Código de uma vez (OTP)

​Convite para organização

​Com template do Kourio

​Três coisas que só aparecem em produção

​Quando não chega

Enviar

Instalar

O mínimo que funciona

Um remetente só, em um lugar só

Link mágico

Código de uma vez (OTP)

Convite para organização

Com template do Kourio

Três coisas que só aparecem em produção

Quando não chega