[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,164 @@
+---
+id: backend-transactional-email
+title: Transactional Email — Resend / SendGrid / 템플릿
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [backend, email, transactional, vibe-coding]
+tech_stack: { language: "TS / React Email", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [transactional email, Resend, SendGrid, Postmark, React Email, MJML, SPF DKIM]
+---
+
+# Transactional Email
+
+> 사용자 행동 트리거 (가입, 영수증). **마케팅과 분리, 별 IP / 별 도메인 권장**. 도구: Resend / Postmark / SendGrid. 템플릿: React Email / MJML. SPF/DKIM/DMARC 필수.
+
+## 📖 핵심 개념
+- Transactional vs Marketing: 다른 IP / 도메인 / sender reputation.
+- SPF / DKIM / DMARC: spoofing 방어 + spam 회피.
+- Bounce / Complaint: 처리 안 하면 reputation 망가짐.
+- Idempotency: 같은 이벤트로 두 번 보내면 안 됨.
+
+## 💻 코드 패턴
+
+### Resend (modern)
+```ts
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+await resend.emails.send({
+  from: 'Acme <noreply@mail.acme.com>',
+  to: user.email,
+  subject: 'Welcome to Acme',
+  html: render(<WelcomeEmail name={user.name} />),
+  headers: { 'X-Idempotency-Key': eventId },
+});
+```
+
+### React Email 템플릿
+```tsx
+import { Body, Container, Head, Heading, Html, Link, Preview, Text } from '@react-email/components';
+
+export function WelcomeEmail({ name }: { name: string }) {
+  return (
+    <Html>
+      <Head />
+      <Preview>Welcome to Acme, {name}</Preview>
+      <Body style={{ backgroundColor: '#f6f9fc', fontFamily: 'system-ui' }}>
+        <Container style={{ padding: '40px 20px' }}>
+          <Heading>Welcome, {name}!</Heading>
+          <Text>Click <Link href="https://acme.com/start">here</Link> to start.</Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+```
+
+```ts
+import { render } from '@react-email/render';
+const html = await render(<WelcomeEmail name="A" />);
+const text = await render(<WelcomeEmail name="A" />, { plainText: true });
+```
+
+### 큐 + retry
+```ts
+// 직접 보내지 말고 큐
+queue.add('email', { to, template, data, idempotencyKey });
+
+queue.process('email', async (job) => {
+  const sent = await db.emails.find(job.data.idempotencyKey);
+  if (sent) return; // 이미 보냄
+
+  const r = await resend.emails.send({...});
+  await db.emails.insert({ idempotencyKey: job.data.idempotencyKey, providerId: r.id });
+});
+```
+
+### Bounce / complaint webhook
+```ts
+app.post('/webhooks/email', async (req, res) => {
+  // SES SNS / SendGrid event webhook / Resend webhook
+  const ev = req.body;
+  if (ev.type === 'email.bounced') {
+    await db.users.update(ev.email, { emailValid: false });
+  }
+  if (ev.type === 'email.complained') {
+    await db.users.update(ev.email, { emailMarketingOptOut: true, emailValid: false });
+  }
+  res.json({ ok: true });
+});
+```
+
+### SPF / DKIM / DMARC DNS
+```
+# SPF
+mail.acme.com.  TXT  "v=spf1 include:_spf.resend.com -all"
+
+# DKIM (Resend / SendGrid 가 제공하는 CNAME)
+resend._domainkey.mail.acme.com.  CNAME  resend._domainkey.acme.com.resend.email.
+
+# DMARC
+_dmarc.mail.acme.com.  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc@acme.com"
+```
+
+### Marketing 분리
+```
+Transactional: noreply@mail.acme.com
+Marketing:     hello@news.acme.com
+```
+
+다른 sub-domain → bounce 가 transactional 평판에 안 영향.
+
+### Plain text + HTML 둘 다
+```ts
+await resend.emails.send({
+  from, to, subject,
+  html: render(<Email />),
+  text: render(<Email />, { plainText: true }), // spam 점수 낮춤
+});
+```
+
+### Preview tools
+- React Email dev server: 라이브 preview.
+- Mailtrap / Litmus: 다양한 client 렌더 테스트.
+
+### 다국어
+```ts
+const html = await render(<WelcomeEmail name={name} t={i18n.t} />, { locale: user.locale });
+```
+
+## 🤔 의사결정 기준
+| 종류 | 추천 |
+|---|---|
+| 작은 SaaS / modern stack | Resend |
+| 큰 규모 / 분석 강함 | SendGrid / Mailgun |
+| Bounce 까다로움 | Postmark (transactional 전문) |
+| 자체 메일 서버 | SES (싸지만 복잡) |
+| Email 아닌 SMS | Twilio / MessageBird |
+| 마케팅 자동화 | Customer.io / Loops |
+
+## ❌ 안티패턴
+- **DKIM 없음**: spam 폴더 직행.
+- **Marketing 같은 도메인**: bounce 가 transactional 평판 망가짐.
+- **Bounce 처리 안 함**: 평판 추락 → 모두 spam.
+- **Throttle 없이 대량**: rate limit hit.
+- **Idempotency 없음**: 같은 이벤트 여러 번 메일.
+- **Plain text 누락**: 일부 client / spam 점수 ↑.
+- **Inline image base64**: 큰 메일 + 일부 client 차단. 호스팅된 URL.
+- **Subject 가 spam-trigger**: "FREE!!!" 같은.
+
+## 🤖 LLM 활용 힌트
+- Resend + React Email + 큐 + bounce webhook 4종.
+- SPF/DKIM/DMARC 자동 사이트 (mxtoolbox) 검증.
+- transactional 따로 sub-domain.
+
+## 🔗 관련 문서
+- [[Backend_Webhook_Patterns]]
+- [[Backend_Job_Queue_Patterns]]
+- [[Frontend_i18n_Patterns]]