Jamail 사용자 가이드 📖

Jamail 사용자 가이드에 오신 것을 환영합니다. 이 문서는 Jamail 이메일 템플릿 관리 시스템의 모든 강력한 기능을 이해하고 활용하는 데 도움을 드립니다.

목차

1. 시작하기
2. 템플릿 관리
3. 고급 기능
   • 다국어 지원
   • A/B 테스팅
   • Multi-SMTP 라우팅
   • 웹훅
4. 설정 및 관리

시작하기

http://localhost:3000에서 Jamail 대시보드에 접속할 수 있습니다. 상단 네비게이션 바의 언어 전환기를 사용하여 한국어와 영어를 전환할 수 있습니다.

대시보드는 다음 정보를 제공합니다:

• 전체 템플릿 수
• 오늘 발송된 이메일
• 최근 활동 로그
• 시스템 상태

템플릿 관리

템플릿 생성하기

1. Templates 페이지로 이동합니다.
2. 새 템플릿 버튼을 클릭합니다.
3. 이름, 고유 키(슬러그), 설명을 입력합니다.
4. 카테고리를 선택합니다 (마케팅, 트랜잭션, 알림 등).

편집 및 미리보기

• 에디터: 분할 화면 에디터를 사용하여 왼쪽에서 HTML을 작성하고 오른쪽에서 미리보기를 확인합니다.
• 변수: 동적 콘텐츠를 위해 Handlebars 구문 ``을 사용합니다.
• 미리보기 데이터: “미리보기” 버튼을 클릭하고 JSON 데이터를 입력하여 변수 치환을 테스트합니다.

버전 관리

• 템플릿을 저장할 때마다 새로운 버전이 생성됩니다.
• 버전 히스토리를 확인하고, 변경 사항을 비교하며, 언제든지 이전 버전으로 롤백할 수 있습니다.

고급 기능

🌐 다국어 지원

수신자의 언어에 자동으로 적응하는 템플릿을 만듭니다.

사용 방법:

1. 템플릿을 열고 번역 탭으로 이동합니다.
2. 언어 추가를 클릭하고 로케일을 선택합니다 (예: 한국어, 일본어).
3. 번역된 제목과 내용을 입력합니다.
4. 발송 시: 이메일을 보낼 때 locale 매개변수를 제공합니다. Jamail이 자동으로 일치하는 번역을 선택합니다.
   • Fallback 로직: 요청된 로케일 → 템플릿 기본 언어 → 시스템 기본 언어

예시:

{
  "to": "user@example.com",
  "locale": "ko",
  "variables": {
    "name": "홍길동"
  }
}

⚖️ A/B 테스팅

다양한 변형을 테스트하여 이메일을 최적화합니다.

사용 방법:

1. 템플릿 에디터에서 A/B 테스팅 탭으로 이동합니다.
2. 변형 생성 (예: “제목 라인 B”)을 클릭합니다.
3. 트래픽 분할을 설정합니다 (예: 50% / 50%).
4. Jamail이 설정한 가중치에 따라 자동으로 트래픽을 분배합니다.
5. 대시보드에서 열람률과 클릭률을 모니터링합니다.
6. 승자 선언을 클릭하여 가장 성과가 좋은 변형을 기본값으로 설정합니다.

메트릭:

• 총 발송 수
• 열람 수 / 열람률
• 클릭 수 / 클릭률
• 전환 수 / 전환율

🔀 Multi-SMTP 라우팅

여러 제공업체를 통해 이메일을 라우팅하여 높은 전달률을 보장합니다.

사용 방법:

1. 설정 > SMTP로 이동합니다.
2. 여러 SMTP 구성을 추가합니다 (예: 마케팅용 AWS SES, 트랜잭션용 SendGrid).
3. 각 SMTP 서버에 카테고리를 할당합니다.
   • 예: “마케팅” 이메일 → AWS SES
   • 예: “알림” → 내부 SMTP
4. 시스템이 템플릿의 카테고리에 따라 자동으로 이메일을 라우팅합니다.

SMTP 설정 예시:

{
  "name": "AWS SES",
  "host": "email-smtp.ap-northeast-2.amazonaws.com",
  "port": 587,
  "username": "AKIAIOSFODNN7EXAMPLE",
  "password": "your-password",
  "categories": ["MARKETING", "NOTIFICATION"]
}

🔔 웹훅

외부 시스템과 통합합니다.

사용 방법:

1. 설정 > 웹훅으로 이동합니다.
2. 웹훅 추가를 클릭합니다.
3. 엔드포인트 URL을 입력하고 이벤트를 선택합니다 (email.sent, email.opened, email.failed).
4. 서명 시크릿을 복사하여 서버에서 페이로드를 검증합니다.
5. 이벤트가 발생할 때마다 Jamail이 JSON 페이로드와 함께 POST 요청을 보냅니다.

이벤트 타입:

• email.sent: 이메일 전송 성공
• email.delivered: 수신자에게 전달됨
• email.opened: 이메일 열람
• email.clicked: 링크 클릭
• email.failed: 전송 실패

페이로드 예시:

{
  "event": "email.sent",
  "timestamp": "2024-12-01T08:00:00Z",
  "data": {
    "templateId": "uuid",
    "recipient": "user@example.com",
    "subject": "환영합니다!",
    "sentAt": "2024-12-01T08:00:00Z"
  }
}

서명 검증:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(JSON.stringify(payload)).digest('hex');
  return signature === expectedSignature;
}

설정 및 관리

API 키

• 백엔드 서비스가 프로그래밍 방식으로 이메일을 트리거할 수 있도록 API 키를 생성합니다.
• 보안을 위해 범위를 할당합니다 (예: send:email, read:templates).

사용 예시:

curl -X POST http://localhost:3001/templates/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "welcome-email",
    "to": "user@example.com",
    "variables": {
      "name": "홍길동"
    }
  }'

사용자 관리 (RBAC)

• Admin: 모든 설정 및 데이터에 대한 전체 액세스
• Operator: 템플릿 생성/편집 및 이메일 발송 가능, 시스템 설정 변경 불가
• Viewer: 읽기 전용 액세스

감사 로그

• 보안 감사를 위해 누가 언제 무엇을 했는지에 대한 자세한 기록을 확인합니다.
• 모든 중요한 작업(템플릿 생성, 수정, 삭제, 설정 변경)이 기록됩니다.

문제 해결

이메일이 발송되지 않는 경우

1. SMTP 설정이 올바른지 확인합니다.
2. Redis와 PostgreSQL이 실행 중인지 확인합니다.
3. 백엔드 로그에서 오류 메시지를 확인합니다.

템플릿 미리보기가 작동하지 않는 경우

1. Handlebars 구문이 올바른지 확인합니다.
2. JSON 변수 데이터가 유효한지 확인합니다.

추가 지원

GitHub Issues에서 문제를 보고하거나 커뮤니티 포럼에 질문을 게시하세요.

즐거운 이메일 관리 되세요! 📧