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.envpara o desenvolvimento local. No Node, nem oastro devnem o servidor compilado carregam o.env, por isso exporte as variáveis ou inicie o servidor comnode --env-file=.env. Veja Secrets & Key Management.
| Variável | Exemplo | Notas |
|---|---|---|
EMAIL_SMTP_HOST | smtp.example.com | Obrigatória |
EMAIL_SMTP_PORT | 587 | Opcional; predefinida 587. Use 465 para TLS implícito |
EMAIL_SMTP_USER | [email protected] | Obrigatória; o início de sessão SMTP |
EMAIL_SMTP_PASS | your-smtp-password | Obrigatória; guarde-a como segredo |
EMAIL_SMTP_SECURE | tls ou starttls | Opcional; a porta 465 usa tls, todas as outras portas usam starttls |
EMAIL_SMTP_FROM | My Site <[email protected]> | Remetente predefinido opcional |
EMAIL_SMTP_FROM_NAME | My Site | Nome 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
-
Instale e ative o plugin de fornecedor, depois abra Settings → Email na administração.
-
Se mais de um plugin de fornecedor estiver instalado, escolha o ativo lá — apenas um entrega de cada vez.
-
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
- Autenticação — links mágicos, convites e fluxos de recuperação que dependem de e-mail
- Referência de hooks de e-mail —
email:beforeSend,email:deliver,email:afterSend