E EmDash CMS Everything Guides, use cases, plugins, templates
Português

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 plugin de fornecedor entrega o correio; escolhe e configura o fornecedor instalando o seu plugin.

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 plugin de 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 — 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 plugin é, 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á selecionado. 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).

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

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 plugin de fornecedor está ativo. Instale e ative um, 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