EmDash는 매직 링크 로그인, 사용자 초대 및 계정 복구에 이메일을 사용합니다. 공급자가 메일을 전송합니다. EmDash에 내장된 SMTP 전송이거나 공급자 플러그인입니다.
이 가이드는 이메일 파이프라인의 작동 방식, 개발 환경에서 기본적으로 얻을 수 있는 것, 프로덕션용 실제 공급자를 연결하는 방법을 다룹니다.
이메일 전송 작동 방식
단일 활성 공급자가 모든 발신 메일을 전송합니다. 공급자가 활성화되어 있지 않으면 이메일이 필요한 기능을 사용할 수 없으며, 초대 링크는 사용자 페이지에서 수동으로 복사하여 공유해야 합니다.
관리자의 Settings → Email에서 현재 상태를 확인할 수 있습니다: 공급자가 활성화되어 있는지, 어떤 공급자인지, 전체 파이프라인을 테스트하는 send test email 버튼이 있습니다.
개발 환경: 내장 콘솔 공급자
개발 환경(astro dev)에서 다른 공급자가 활성화되지 않은 경우 EmDash는 내장 콘솔 공급자를 자동으로 활성화합니다. 아무것도 보내지 않고 — 각 이메일을 터미널에 기록하고 마지막 100개 메시지를 메모리에 보관합니다.
즉, 매직 링크와 초대는 개발 환경에서 기본적으로 작동합니다: 매직 링크를 요청한 다음 터미널 출력에서 URL을 복사합니다. 개발 전용 엔드포인트 GET /_emdash/api/dev/emails에서 캡처된 이메일을 나열할 수도 있습니다(DELETE로 삭제).
공급자 플러그인을 추가하거나 SMTP를 설정한 후에도 Settings → Email에 콘솔이 계속 표시되면, 그곳에서 해당 공급자를 선택하고 저장하세요.
콘솔 공급자는 개발 전용이며 프로덕션 빌드에서는 실행되지 않습니다.
프로덕션: 내장 SMTP 전송
SMTP 자격 증명이 있다면(예: Brevo, Office 365, Fastmail, Amazon SES 또는 자체 메일 서버), EmDash는 플러그인 없이 이를 통해 전송할 수 있습니다. 이 전송은 인증하기 전에 TLS를 요구하고, AUTH PLAIN과 AUTH LOGIN을 지원하며, 25번 포트를 거부합니다.
다음 두 가지 방법으로 구성할 수 있습니다.
- 관리자에서: Settings → Email을 열고 SMTP를 선택한 다음 서버 정보를 입력하고 저장합니다. 저장하면 설정이 데이터베이스에 저장되고 SMTP가 선택됩니다. EmDash는 비밀번호를
EMDASH_ENCRYPTION_KEY로 암호화하므로 이 키가 설정되어 있어야 합니다. 관리자에서 저장한 설정은 환경 변수보다 우선하므로, 비밀번호를 교체할 때는 관리자에서 변경하세요. - 환경 변수로: 다음 변수를 서버의 프로세스 환경에 설정합니다. Cloudflare에서는
wrangler secret put을, 로컬 개발에서는.env를 사용합니다. Node에서는astro dev도 빌드된 서버도.env를 로드하지 않으므로, 변수를 export하거나node --env-file=.env로 서버를 시작하세요. Secrets & Key Management를 참조하세요.
| 변수 | 예시 | 참고 |
|---|---|---|
EMAIL_SMTP_HOST | smtp.example.com | 필수 |
EMAIL_SMTP_PORT | 587 | 선택 사항. 기본값은 587. 암시적 TLS에는 465 사용 |
EMAIL_SMTP_USER | [email protected] | 필수. SMTP 로그인 |
EMAIL_SMTP_PASS | your-smtp-password | 필수. 시크릿으로 저장하세요 |
EMAIL_SMTP_SECURE | tls 또는 starttls | 선택 사항. 465번 포트는 tls, 다른 모든 포트는 starttls 사용 |
EMAIL_SMTP_FROM | My Site <[email protected]> | 선택 사항인 기본 발신자 |
EMAIL_SMTP_FROM_NAME | My Site | EMAIL_SMTP_FROM_EMAIL에 대한 선택 사항인 표시 이름 |
EMAIL_SMTP_FROM_EMAIL | [email protected] | 선택 사항인 발신자 주소. EMAIL_SMTP_FROM보다 우선 |
EMAIL_SMTP_REPLY_TO | [email protected] | 선택 사항인 Reply-To 주소 |
발신자 변수가 없으면 EmDash는 EMAIL_SMTP_USER로 전송합니다. SMTP 로그인이 이메일 주소가 아니라면 EMAIL_SMTP_FROM_EMAIL 또는 EMAIL_SMTP_FROM을 설정하세요. 그렇지 않으면 전송이 Invalid sender address for SMTP delivery와 함께 실패합니다. 이 경우 Settings → Email은 저장하기 전에 발신자 이메일을 요청합니다.
환경 변수가 모두 갖춰지면, 이메일 공급자 플러그인이 활성화되어 있거나 Settings → Email에서 다른 공급자가 선택된 경우를 제외하고 EmDash는 SMTP로 전송합니다. 공급자 플러그인과 함께 계속 SMTP를 사용하려면 그곳에서 SMTP를 선택하고 저장하세요.
Cloudflare Workers에서는 이 전송에 nodejs_compat 호환성 플래그가 필요합니다. Cloudflare 배포 가이드를 참조하세요.
프로덕션: 공급자 플러그인 설치
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를 사용해서는 안 됩니다.
공급자 선택 및 테스트
-
공급자 플러그인을 설치하고 활성화한 다음 관리자에서 Settings → Email을 엽니다.
-
둘 이상의 공급자 플러그인이 설치된 경우 거기서 활성 플러그인을 선택합니다 — 한 번에 하나만 전송합니다.
-
Send test email을 사용하여 전체 파이프라인을 엔드투엔드로 확인합니다. 결과는 전송 오류를 직접 표시하므로 자격 증명을 디버그하는 가장 빠른 방법입니다.
문제 해결
- “No email provider is configured”: 활성화된 공급자가 없습니다. SMTP를 구성하거나 공급자 플러그인을 활성화한 다음 Settings → Email에서 선택합니다.
- 매직 링크/초대가 조용히 사용 불가 — 같은 원인. 공급자 없이 사용자 페이지는 여전히 초대를 생성하지만 초대 링크를 수동으로 복사해야 합니다.
- 개발 환경에서 작동하지만 프로덕션에서 실패 — 개발 환경은 내장 콘솔 공급자를 사용하여 누락된 프로덕션 공급자를 가립니다. 배포된 사이트에서 Settings → Email을 확인하세요.
- 이메일이 스팸으로 이동 — 이메일 공급자에서 발신 도메인에 대한 SPF/DKIM/DMARC를 구성합니다; 이는 공급자 측이며 EmDash 설정이 아닙니다.