트랜잭셔널 이메일을 Cloudflare Email Service로 마이그레이션하기

이 코드베이스의 아웃바운드 이메일을 현재 제공업체(Postmark / SES / Resend / SendGrid / Mailgun 등)에서 Cloudflare Email Service(2026년 4월 출시된 공개 베타)로 마이그레이션하려고 합니다. 신중하게 도와주세요. ## 컨텍스트: Cloudflare Email Service란 무엇인가 Cloudflare의 새로운 트랜잭션 이메일 API입니다. 엔드포인트: ``` POST https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/email/sending/send Authorization: Bearer {API_TOKEN} Content-Type: application/json ``` 요청 본문: ```json { "to": "user@example.com", // 문자열 또는 문자열 배열 "from": "no-reply@yourdomain.com", // 문자열 또는 {"address":"x@y","name":"Display"} "subject": "...", "html": "<p>...</p>", // 선택 사항 "text": "...", // 선택 사항 (html/text 중 하나는 필수) "cc": ["..."], // 선택 사항, 배열 "bcc": ["..."], // 선택 사항, 배열 "reply_to": "...", // 선택 사항, 단일 문자열 "headers": {"List-Unsubscribe": "<...>"} // 선택 사항, 예: 뉴스레터용 } ``` 성공 응답: HTTP 200 + `{"success":true,"result":{"delivered":[],"queued":[],"permanent_bounces":[]}}`. 실패: 200이 아닌 경우 또는 `success:false` 또는 비어 있지 않은 `permanent_bounces`. 세 가지를 모두 항상 확인하세요. 가격: 월 $5 Workers Paid 플랜 + 이메일 3,000건 무료 + 이후 1,000건당 $0.35. Postmark보다 약 5배 저렴합니다. 배치 전송 엔드포인트 없음 - 단일 전송을 반복하세요. ## 따라야 할 단계 ### 1. 사전 요구 사항 확인 코드를 작성하기 전에 다음을 확인하도록 요청하세요: - Cloudflare Workers Paid 플랜($5/월) 보유 - Cloudflare 대시보드 → Email → Email Sending → Onboard Domain에서 발신자 도메인을 온보딩 완료(SPF/DKIM/DMARC + cf-bounce MX 레코드 자동 추가됨) - `email_sending:write` 범위의 API 토큰 보유(https://dash.cloudflare.com → Custom Token에서 생성) - Cloudflare 계정 ID 보유 이러한 항목을 확인하기 전에는 진행하지 마세요. ### 2. 도메인 평판 전략 권장 대부분의 앱은 발신자를 2-3개의 서브도메인으로 분할하여 한 도메인의 스팸 신고가 다른 도메인의 전달성에 부정적 영향을 미치지 않도록 해야 합니다: - `mail.<domain>` 또는 `members.<domain>` → 트랜잭션(로그인, 영수증, 비밀번호 재설정, 앱 내 알림) - `e.<domain>` → 콜드/리커버리(장바구니 포기, 재유치 캠페인) - `newsletter.<domain>` → List-Unsubscribe 헤더가 있는 옵트인 뉴스레터 각 서브도메인은 Cloudflare에서 별도로 온보딩해야 합니다. 어떤 것을 원하는지 물어보세요. ### 3. 기존 이메일 전송 감사 grep/search를 사용하여 이 코드베이스에서 이메일을 전송하는 모든 위치를 찾으세요. 다음을 찾으세요: - 현재 제공업체의 SDK 클래스 이름, API URL, 환경/설정 변수 - `mail()`, SMTP 사용, `nodemailer` 등과 같은 일반적인 패턴 파일별이 아닌 이메일 유형/목적별로 결과를 그룹화하세요(예: "매직 링크 로그인", "결제 영수증", "주간 뉴스레터"). 변경하기 전에 찾은 내용을 알려주세요. ### 4. 단일 헬퍼 함수 추가 코드베이스 전체에 Cloudflare API 호출을 흩뿌리지 마세요. 하나의 헬퍼(제공업체별 이름 예: `sendEmailViaCloudflare()`)를 추가하세요: - 설정 변수에서 `from`을 기본값으로 사용(하드코딩 금지) - `"Name <email@domain>"` 문자열을 API의 `{address, name}` 객체 형태로 파싱 - `cc`/`bcc`를 문자열 또는 배열로 허용 - `headers` 딕셔너리 허용(뉴스레터는 `List-Unsubscribe` + `List-Unsubscribe-Post` 필요) - `bool` 반환(성공 시 true, 실패 시 false) - 실패 시 내가 볼 수 있는 곳에 로그/알림(Telegram, Sentry, 로그 파일 - 코드베이스가 이미 사용하는 방식과 일치) - curl/fetch 타임아웃 설정(연결 5초, 총 15초)으로 Cloudflare API가 멈춰도 요청이 지연되지 않도록 함 - `permanent_bounces: [...]`가 비어 있지 않으면 소프트 실패로 처리 ### 5. 먼저 위험도가 낮은 이메일 유형 하나만 마이그레이션 모든 것을 한 번에 마이그레이션하지 마세요. 감사에서 위험도가 가장 낮은 이메일 유형을 선택하세요(스팸으로 분류되어도 돈이나 사용자를 잃지 않는 것 - 예: "내부 관리자 알림", "프로필 사진 거부"). 해당 유형만 마이그레이션하세요. 엔드투엔드로 테스트하세요. 이메일이 실제로 도착하는지 확인하세요. 그런 다음에만 다음 마이그레이션을 제안하세요. ### 6. 로그인 이메일 마이그레이션 중단 코드베이스가 매직 링크 로그인 또는 비밀번호 재설정 이메일을 전송하는 경우, 해당 이메일을 아직 Cloudflare로 마이그레이션하지 마세요. Cloudflare Email Service는 매우 새로운 제품입니다(작성 시점 기준 약 1개월). IP/도메인 평판이 검증되지 않았습니다. 로그인 이메일이 스팸으로 분류되면 사용자가 잠깁니다. 위험도가 낮은 유형에서 최소 3개월간 깨끗한 전달성 데이터가 나올 때까지 현재 제공업체를 유지하세요. 이 점을 명시적으로 알려주세요. ### 7. 커밋 경계 제안 각 마이그레이션 성공 후 명확한 메시지와 함께 집중된 git 커밋을 제안하세요. 관련 없는 변경 사항을 묶지 마세요. ## 알려야 할 중요한 주의 사항 - 베타 제품입니다. 가격이 완전히 확정되지 않았습니다. SLA가 정의되지 않았습니다. 변경될 수 있습니다. - 배치 엔드포인트가 없습니다. 대량 전송(1,000명 이상 수신자 뉴스레터)은 반복이 필요합니다 - 전송당 약 150ms로 1,000건당 약 2.5분. 크론에는 적합하지만 동기식 사용자 대면 흐름에는 좋지 않습니다. - 바운스 웹훅이 아직 없습니다. 응답 본문의 `permanent_bounces` 배열을 통해 실패를 표시하세요. - 억제 목록이 자동 관리됩니다. 하드 바운스, 반복된 소프트 바운스, 스팸 신고가 차단됩니다. 스팸 신고 억제는 제거하기 어렵습니다(남용 방지). - 메시지별 로그/대시보드가 아직 없습니다. 추적이 필요하면 응답의 `messageId`를 사용하세요. - List-Unsubscribe 헤더는 그대로 전달됩니다 - Gmail의 대량 발신자 요구 사항은 여전히 충족되지만 `headers`에 포함해야 합니다. ## 첫 번째 조치 코드를 작성하기 전에: 1단계(사전 요구 사항 확인)와 3단계(기존 전송 감사)를 수행한 다음, 추론에 대한 간략한 설명과 함께 마이그레이션 순서를 제안하세요. 변경하기 전에 내 확인을 기다리세요.