docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -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]]
|
||||
Reference in New Issue
Block a user