E EmDash CMS Everything Guides, use cases, plugins, templates
한국어

이메일 설정

이 페이지

EmDash는 매직 링크 로그인, 사용자 초대 및 계정 복구에 이메일을 사용합니다. 공급자 플러그인이 메일을 전송합니다; 플러그인을 설치하여 공급자를 선택하고 구성합니다.

이 가이드는 이메일 파이프라인의 작동 방식, 개발 환경에서 기본적으로 얻을 수 있는 것, 프로덕션용 실제 공급자를 연결하는 방법을 다룹니다.

이메일 전송 작동 방식

단일 활성 공급자 플러그인이 모든 발신 메일을 전송합니다. 공급자가 활성화되어 있지 않으면 이메일이 필요한 기능을 사용할 수 없습니다 — 초대 링크는 사용자 페이지에서 수동으로 복사하여 공유해야 합니다.

관리자의 Settings → Email에서 현재 상태를 확인할 수 있습니다: 공급자가 활성화되어 있는지, 어떤 플러그인인지, 전체 파이프라인을 테스트하는 send test email 버튼이 있습니다.

개발 환경: 내장 콘솔 공급자

개발 환경(astro dev)에서 다른 공급자가 선택되지 않은 경우 EmDash는 내장 콘솔 공급자를 자동으로 활성화합니다. 아무것도 보내지 않고 — 각 이메일을 터미널에 기록하고 마지막 100개 메시지를 메모리에 보관합니다.

즉, 매직 링크와 초대는 개발 환경에서 기본적으로 작동합니다: 매직 링크를 요청한 다음 터미널 출력에서 URL을 복사합니다. 개발 전용 엔드포인트 GET /_emdash/api/dev/emails에서 캡처된 이메일을 나열할 수도 있습니다(DELETE로 삭제).

콘솔 공급자는 개발 전용이며 프로덕션 빌드에서는 실행되지 않습니다.

프로덕션: 공급자 플러그인 설치

Cloudflare Workers

Cloudflare에서는 @emdash-cms/cloudflare/plugins의 cloudflareEmail() 플러그인을 사용합니다. Worker send_email 바인딩을 통해 Cloudflare Email Sending으로 전송하므로 외부 계정이나 API 키가 필요하지 않습니다. Cloudflare 배포 가이드는 발신자 도메인 온보딩, 바인딩 추가 및 플러그인 등록을 안내합니다.

Node 및 기타 플랫폼

커뮤니티 유지 관리 emdash-smtp 플러그인 패밀리는 일반 SMTP와 호스팅 공급자를 포함하며, Amazon SES, Brevo, Mailgun, Postmark, Resend, SendGrid, Zoho 등이 포함됩니다.

pnpm add emdash-smtp

다음 구성은 플러그인을 EmDash에 등록합니다:

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

export default defineConfig({
	integrations: [
		emdash({
			// ...데이터베이스/스토리지 설정
			plugins: [emdashSmtp()],
		}),
	],
});

공급자 자격 증명은 플러그인 자체 설정을 통해 구성됩니다 — 공급자 매트릭스 및 설정 세부 정보는 README를 참조하세요.

공급자 자격 증명 저장 위치

공급자 플러그인은 API 키와 비밀번호를 플러그인 설정으로 선언합니다. 관리자의 플러그인 설정 페이지에서 입력합니다; EmDash는 다른 플러그인 설정과 함께 데이터베이스에 저장하며, 키를 회전하려면 새 값을 거기에 붙여넣습니다. Secrets & Key Management는 스토리지와 주의 사항을 설명합니다.

플러그인이 배포 시크릿(wrangler secret put, .env)을 대신 읽을 수 있는지 여부는 형식에 따라 다르므로 README를 따르세요. 샌드박스 플러그인은 process.env 또는 플랫폼 바인딩에 액세스할 수 없습니다. 네이티브 플러그인은 process.env를 읽을 수 있습니다; 빌드 시간에 인라인되어 빌드 머신의 값을 번들에 구워넣는 import.meta.env를 사용해서는 안 됩니다.

공급자 선택 및 테스트

  1. 공급자 플러그인을 설치하고 활성화한 다음 관리자에서 Settings → Email을 엽니다.

  2. 둘 이상의 공급자 플러그인이 설치된 경우 거기서 활성 플러그인을 선택합니다 — 한 번에 하나만 전송합니다.

  3. Send test email을 사용하여 전체 파이프라인을 엔드투엔드로 확인합니다. 결과는 전송 오류를 직접 표시하므로 자격 증명을 디버그하는 가장 빠른 방법입니다.

문제 해결

  • “No email provider is configured” — 공급자 플러그인이 활성화되지 않았습니다. 설치하고 활성화한 다음 Settings → Email에서 선택합니다.
  • 매직 링크/초대가 조용히 사용 불가 — 같은 원인. 공급자 없이 사용자 페이지는 여전히 초대를 생성하지만 초대 링크를 수동으로 복사해야 합니다.
  • 개발 환경에서 작동하지만 프로덕션에서 실패 — 개발 환경은 내장 콘솔 공급자를 사용하여 누락된 프로덕션 공급자를 가립니다. 배포된 사이트에서 Settings → Email을 확인하세요.
  • 이메일이 스팸으로 이동 — 이메일 공급자에서 발신 도메인에 대한 SPF/DKIM/DMARC를 구성합니다; 이는 공급자 측이며 EmDash 설정이 아닙니다.

관련

  • 인증 — 이메일에 의존하는 매직 링크, 초대 및 복구 플로우
  • 이메일 훅 참조 — email:beforeSend, email:deliver, email:afterSend