Configuração de e-mail

Nesta página

O EmDash usa e-mail para login com link mágico, convites de utilizador e recuperação de conta. Um fornecedor entrega o correio: o transporte SMTP integrado no EmDash ou um plugin de fornecedor.

Este guia cobre como funciona o pipeline de e-mail, o que obtém pronto a usar em desenvolvimento e como ligar um fornecedor real para produção.

Como funciona a entrega de e-mail

Um único fornecedor ativo entrega todo o correio de saída. Se nenhum fornecedor estiver ativo, as funcionalidades que precisam de e-mail não estão disponíveis e os links de convite devem então ser copiados e partilhados manualmente da página de Utilizadores.

Pode ver o estado atual em Settings → Email na administração: se um fornecedor está ativo, qual fornecedor é, e um botão send test email que exercita o pipeline completo.

Desenvolvimento: Fornecedor de consola integrado

Em desenvolvimento (astro dev), o EmDash ativa automaticamente um fornecedor de consola integrado quando nenhum outro fornecedor está ativo. Não envia nada — regista cada e-mail no terminal e mantém as últimas 100 mensagens na memória.

Isso significa que links mágicos e convites funcionam prontos a usar em desenvolvimento: solicite um link mágico, depois copie o URL da sua saída do terminal. Também pode listar e-mails capturados no endpoint exclusivo de desenvolvimento GET /_emdash/api/dev/emails (e limpá-los com DELETE).

Se Settings → Email continuar a mostrar a consola depois de adicionar um plugin de fornecedor ou de configurar o SMTP, selecione aí esse fornecedor e guarde.

O fornecedor de consola é exclusivo de desenvolvimento e nunca é executado em builds de produção.

Produção: Transporte SMTP integrado

Se tem credenciais SMTP (por exemplo, Brevo, Office 365, Fastmail, Amazon SES ou o seu próprio servidor de correio), o EmDash pode enviar através delas sem um plugin. O transporte exige TLS antes de se autenticar, suporta AUTH PLAIN e AUTH LOGIN e recusa a porta 25.

Pode configurá-lo de duas formas:

  • No admin: abra Settings → Email, escolha SMTP, preencha os dados do servidor e guarde. Ao guardar, as definições são armazenadas na base de dados e o SMTP é selecionado. O EmDash cifra a palavra-passe com EMDASH_ENCRYPTION_KEY, por isso essa chave tem de estar definida. As definições guardadas no admin têm prioridade sobre as variáveis de ambiente, por isso altere a palavra-passe no admin quando a rodar.
  • Com variáveis de ambiente: defina as seguintes variáveis no ambiente de processo do servidor. No Cloudflare, use wrangler secret put, e .env para o desenvolvimento local. No Node, nem o astro dev nem o servidor compilado carregam o .env, por isso exporte as variáveis ou inicie o servidor com node --env-file=.env. Veja Secrets & Key Management.
VariávelExemploNotas
EMAIL_SMTP_HOSTsmtp.example.comObrigatória
EMAIL_SMTP_PORT587Opcional; predefinida 587. Use 465 para TLS implícito
EMAIL_SMTP_USER[email protected]Obrigatória; o início de sessão SMTP
EMAIL_SMTP_PASSyour-smtp-passwordObrigatória; guarde-a como segredo
EMAIL_SMTP_SECUREtls ou starttlsOpcional; a porta 465 usa tls, todas as outras portas usam starttls
EMAIL_SMTP_FROMMy Site <[email protected]>Remetente predefinido opcional
EMAIL_SMTP_FROM_NAMEMy SiteNome de apresentação opcional para EMAIL_SMTP_FROM_EMAIL
EMAIL_SMTP_FROM_EMAIL[email protected]Endereço de remetente opcional; tem prioridade sobre EMAIL_SMTP_FROM
EMAIL_SMTP_REPLY_TO[email protected]Endereço Reply-To opcional

Sem uma variável de remetente, o EmDash envia a partir de EMAIL_SMTP_USER. Se o seu início de sessão SMTP não for um endereço de e-mail, defina EMAIL_SMTP_FROM_EMAIL ou EMAIL_SMTP_FROM, caso contrário a entrega falha com Invalid sender address for SMTP delivery. Nesse caso, Settings → Email pede um e-mail de remetente antes de guardar.

Quando as variáveis de ambiente estão completas, o EmDash envia por SMTP, a menos que um plugin de fornecedor de e-mail esteja ativo ou que outro fornecedor esteja selecionado em Settings → Email. Para continuar a usar o SMTP em conjunto com um plugin de fornecedor, selecione aí SMTP e guarde.

No Cloudflare Workers, o transporte precisa da flag de compatibilidade nodejs_compat. Veja o guia de implantação no Cloudflare.

Produção: Instalar um plugin de fornecedor

Cloudflare Workers

No Cloudflare, use o plugin cloudflareEmail() de @emdash-cms/cloudflare/plugins. Envia através do Cloudflare Email Sending sobre um binding send_email do Worker, portanto não precisa de conta externa ou chave API. O guia de deployment Cloudflare orienta através do onboarding do domínio remetente, adição do binding e registo do plugin.

Node e outras plataformas

A família de plugins mantida pela comunidade emdash-smtp cobre SMTP genérico mais fornecedores hospedados, incluindo Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho e mais.

pnpm add emdash-smtp

A seguinte configuração regista o plugin com o EmDash:

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { emdashSmtp } from "emdash-smtp";

export default defineConfig({
	integrations: [
		emdash({
			// ...a sua configuração de base de dados/armazenamento
			plugins: [emdashSmtp()],
		}),
	],
});

As credenciais do fornecedor são configuradas através das próprias definições do plugin — veja o seu README para a matriz de fornecedores e detalhes de configuração.

Onde residem as credenciais do fornecedor

Os plugins de fornecedor declaram as suas chaves API e passwords como definições de plugin. Insira-as na página de definições do plugin na administração; o EmDash armazena-as na base de dados junto com outras definições de plugin, e rodar uma chave significa colar o novo valor lá. Secrets & Key Management descreve o armazenamento e as suas ressalvas.

Se um plugin pode ler um segredo de deployment (wrangler secret put, .env) depende do seu formato, por isso siga o seu README. Plugins sandbox não podem aceder a process.env ou bindings de plataforma. Um plugin nativo pode ler process.env; não deve usar import.meta.env, que é incorporado no momento da compilação e cozinha o valor da máquina de build no bundle.

Selecionar um fornecedor e testar

  1. Instale e ative o plugin de fornecedor, depois abra Settings → Email na administração.

  2. Se mais de um plugin de fornecedor estiver instalado, escolha o ativo lá — apenas um entrega de cada vez.

  3. Use Send test email para verificar o pipeline completo de ponta a ponta. O resultado revela erros de entrega diretamente, que é a forma mais rápida de depurar credenciais.

Resolução de problemas

  • “No email provider is configured”: nenhum fornecedor está ativo. Configure o SMTP ou ative um plugin de fornecedor e depois selecione-o em Settings → Email.
  • Links mágicos/convites silenciosamente indisponíveis — mesma causa. Sem fornecedor, a página de Utilizadores ainda cria convites, mas deve copiar o link de convite manualmente.
  • Funciona em desenvolvimento, falha em produção — o desenvolvimento usa o fornecedor de consola integrado, que mascara um fornecedor de produção em falta. Verifique Settings → Email no site implementado.
  • E-mails chegam ao spam — configure SPF/DKIM/DMARC para o seu domínio de envio no seu fornecedor de e-mail; isto é do lado do fornecedor, não uma definição EmDash.

Relacionado