🧾

★ Pinned

API 명세서를 만들어보자!

2025.09.26

알림(Notification) 시스템 API 명세서 및 아키텍처

1. 개요

글 작성에 앞서 알림(Notification) 도메인 중 이메일 알림 시스템을 담당하는 API 명세서와 아키텍처 구조를 정리했습니다. 주요 구성 요소는 email_templates(템플릿 관리)와 email_sends(발송 이력 관리) 두 개의 테이블로 구성되어 있습니다.

2. 시스템 아키텍처

flowchart LR
    Client[사용자/서비스] -->|API 호출| API[Notification API 서버]
    API --> DB[(Notification DB)]
    API --> Mail[메일 전송 서비스]
    DB <--> API

    subgraph "Notification DB"
        T[email_templates]
        S[email_sends]
    end

3. ERD 구조

erDiagram
    email_templates {
        bigint id PK
        string template_name
        string subject
        text html_content
        text text_content
        json variables
        enum status
        timestamp created_at
        timestamp updated_at
    }

    email_sends {
        bigint id PK
        bigint template_id FK
        string to_email
        string subject
        text content
        enum status
        json send_result
        timestamp sent_at
        timestamp created_at
    }

    email_templates ||--o{ email_sends : "template_id"

4. API 명세서

기본 정보

Base URL: https://api.paystream.com/v1
인증 방식: JWT
응답 형식: JSON

공통 규칙

사용 Method: GET POST PUT DELETE
모든 인증이 필요한 요청은 헤더에 Authorization: Bearer <access_token> 포함
날짜/시간은 ISO 8601 형식(YYYY-MM-DDThh:mm:ssZ)
ENUM 필드는 API 문서에서 허용 값과 기본값을 명시

공통 에러 응답 포맷

{
  "error": {
    "code": "ERROR_CODE",
    "message": "에러 메시지",
    "details": {}
  }
}

이메일 템플릿 API

1. 템플릿 목록 조회

설명: 등록된 이메일 템플릿 목록을 페이지네이션과 함께 조회합니다. 템플릿 상태별 필터링이 가능하며, 관리자가 템플릿을 관리할 때 사용됩니다.

Request

HTTP Method: GET
URI: /notifications/email-templates
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json
Query Parameters:
- page (선택): 페이지 번호 (기본값: 1)
- limit (선택): 페이지당 항목 수 (기본값: 20, 최대: 100)
- status (선택): 템플릿 상태 필터 (active, inactive)

Response (200)

{
  "data": [
    {
      "id": 1,
      "template_name": "welcome_email",
      "subject": "환영합니다!",
      "status": "active",
      "variables": ["username", "verification_link"],
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 95,
    "per_page": 20
  }
}

2. 템플릿 상세 조회

설명: 특정 템플릿의 상세 정보를 조회합니다. HTML/텍스트 콘텐츠와 사용 가능한 변수 목록을 포함하여, 템플릿 편집이나 발송 시 참고용으로 사용됩니다.

Request

HTTP Method: GET
URI: /notifications/email-templates/{template_id}
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json

Response (200)

{
  "data": {
    "id": 1,
    "template_name": "welcome_email",
    "subject": "환영합니다, {{username}}님!",
    "html_content": "<html>...</html>",
    "text_content": "환영합니다...",
    "variables": ["username", "verification_link"],
    "status": "active",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z"
  }
}

3. 템플릿 생성

설명: 새로운 이메일 템플릿을 생성합니다. HTML과 텍스트 버전을 모두 지원하며, 동적 변수 치환을 위한 변수 목록을 정의할 수 있습니다. 마케팅팀이나 개발팀에서 새로운 이메일 템플릿을 추가할 때 사용됩니다.

Request

HTTP Method: POST
URI: /notifications/email-templates
Headers:
- Authorization: Bearer <access_token>
- Content-Type: application/json
- Accept: application/json
Body:

{
  "template_name": "welcome_new_user",
  "subject": "환영합니다, {{username}}님!",
  "html_content": "<html><body><h1>환영합니다!</h1><p>안녕하세요, {{username}}님. 가입을 환영합니다.</p><a href=\"{{verification_link}}\">이메일 인증하기</a></body></html>",
  "text_content": "환영합니다, {{username}}님! 가입을 환영합니다. 이메일 인증: {{verification_link}}",
  "variables": ["username", "verification_link"],
  "status": "active"
}

Response (201)

{
  "data": {
    "id": 15,
    "template_name": "welcome_new_user",
    "subject": "환영합니다, {{username}}님!",
    "html_content": "<html><body><h1>환영합니다!</h1><p>안녕하세요, {{username}}님. 가입을 환영합니다.</p><a href=\"{{verification_link}}\">이메일 인증하기</a></body></html>",
    "text_content": "환영합니다, {{username}}님! 가입을 환영합니다. 이메일 인증: {{verification_link}}",
    "variables": ["username", "verification_link"],
    "status": "active",
    "created_at": "2024-01-25T10:15:00Z",
    "updated_at": "2024-01-25T10:15:00Z"
  }
}

4. 템플릿 수정

설명: 기존 템플릿의 내용을 수정합니다. 제목, HTML/텍스트 콘텐츠, 상태 등을 업데이트할 수 있으며, 부분 수정도 지원합니다. 템플릿 내용 변경이나 비활성화 시 사용됩니다.

Request

HTTP Method: PUT
URI: /notifications/email-templates/{template_id}
Headers:
- Authorization: Bearer <access_token>
- Content-Type: application/json
- Accept: application/json
Body:

{
  "subject": "비밀번호 재설정 요청",
  "html_content": "<html><body>수정된 내용...</body></html>",
  "status": "active"
}

Response (200)

{
  "data": {
    "id": 15,
    "template_name": "password_reset",
    "subject": "비밀번호 재설정 요청",
    "html_content": "<html><body>수정된 내용...</body></html>",
    "text_content": "안녕하세요, {{username}}님...",
    "variables": ["username", "reset_link", "expire_time"],
    "status": "active",
    "created_at": "2024-01-25T10:15:00Z",
    "updated_at": "2024-01-25T15:30:00Z"
  }
}

5. 템플릿 삭제

설명: 더 이상 사용하지 않는 템플릿을 완전히 삭제합니다. 삭제 전에 해당 템플릿이 사용 중인지 확인하며, 사용 중인 템플릿은 삭제할 수 없습니다. 관리자가 불필요한 템플릿을 정리할 때 사용됩니다.

Request

HTTP Method: DELETE
URI: /notifications/email-templates/{template_id}
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json

Response (204)

No Content

이메일 발송 API

1. 이메일 발송 이력 조회

설명: 이메일 발송 이력을 조회합니다. 템플릿, 수신자, 발송 상태, 날짜별로 필터링이 가능하며, 관리자가 발송 현황을 모니터링하거나 문제가 발생한 이메일을 추적할 때 사용됩니다.

Request

HTTP Method: GET
URI: /notifications/email-sends
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json
Query Parameters:
- page (선택): 페이지 번호 (기본값: 1)
- limit (선택): 페이지당 항목 수 (기본값: 20, 최대: 100)
- template_id (선택): 템플릿 ID 필터
- status (선택): 발송 상태 필터 (pending, sent, failed)
- to_email (선택): 수신자 이메일 필터
- date_from (선택): 시작 날짜 (YYYY-MM-DD)
- date_to (선택): 종료 날짜 (YYYY-MM-DD)

Response (200)

{
  "data": [
    {
      "id": 1001,
      "template_id": 1,
      "template_name": "welcome_email",
      "to_email": "user@example.com",
      "subject": "환영합니다, 홍길동님!",
      "status": "sent",
      "sent_at": "2024-01-25T10:30:00Z",
      "created_at": "2024-01-25T10:29:45Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 25,
    "total_items": 487,
    "per_page": 20
  }
}

2. 발송 이력 상세 조회

설명: 특정 이메일 발송의 상세 정보를 조회합니다. 실제 발송된 내용, 발송 결과, 에러 정보 등을 포함하여, 발송 실패 원인 분석이나 고객 문의 대응 시 사용됩니다.

Request

HTTP Method: GET
URI: /notifications/email-sends/{send_id}
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json

Response (200)

{
  "data": {
    "id": 1001,
    "template_id": 1,
    "template_name": "welcome_email",
    "to_email": "user@example.com",
    "subject": "환영합니다, 홍길동님!",
    "content": "<html><body>실제 발송된 HTML 내용...</body></html>",
    "status": "sent",
    "send_result": {
      "message_id": "0123456789abcdef",
      "provider": "aws_ses",
      "response_code": 200
    },
    "sent_at": "2024-01-25T10:30:00Z",
    "created_at": "2024-01-25T10:29:45Z"
  }
}

3. 이메일 발송 요청

설명: 개별 이메일을 발송합니다. 기존 템플릿을 사용하여 변수를 치환한 후 즉시 또는 예약 발송할 수 있습니다. 회원가입, 비밀번호 재설정, 주문 확인 등 개별 사용자에게 보내는 이메일 발송 시 사용됩니다.

Request

HTTP Method: POST
URI: /notifications/email-sends
Headers:
- Authorization: Bearer <access_token>
- Content-Type: application/json
- Accept: application/json
Body:

{
  "template_id": 1,
  "to_email": "newuser@example.com",
  "variables": {
    "username": "박상우",
    "verification_link": "https://paystream.com/verify?token=abc123"
  },
  "send_immediately": true
}

Response (201)

{
  "data": {
    "id": 1002,
    "template_id": 1,
    "to_email": "newuser@example.com",
    "subject": "안녕하세요, 박상우님!",
    "status": "pending",
    "created_at": "2024-01-25T11:00:00Z"
  }
}

4. 대량 이메일 발송 요청

설명: 여러 수신자에게 동시에 이메일을 발송합니다. 마케팅 캠페인, 공지사항, 프로모션 등 대량 이메일 발송 시 사용되며, 각 수신자별로 다른 변수를 적용할 수 있습니다. 발송량이 많을 경우 큐에 등록되어 순차적으로 처리됩니다.

Request

HTTP Method: POST
URI: /notifications/email-sends/bulk
Headers:
- Authorization: Bearer <access_token>
- Content-Type: application/json
- Accept: application/json
Body:

{
  "template_id": 2,
  "recipients": [
    {
      "to_email": "user1@example.com",
      "variables": {
        "username": "사용자1",
        "promotion_code": "SAVE20"
      }
    },
    {
      "to_email": "user2@example.com",
      "variables": {
        "username": "사용자2",
        "promotion_code": "SAVE25"
      }
    }
  ],
  "send_immediately": false,
  "scheduled_at": "2024-01-26T09:00:00Z"
}

Response (202)

{
  "data": {
    "batch_id": "batch_abc123",
    "template_id": 2,
    "recipient_count": 2,
    "status": "queued",
    "scheduled_at": "2024-01-26T09:00:00Z",
    "created_at": "2024-01-25T15:30:00Z"
  }
}

5. 발송 재시도

설명: 실패한 이메일 발송을 다시 시도합니다. 네트워크 오류, 일시적인 서버 문제 등으로 발송이 실패한 경우, 원본 발송 정보를 기반으로 새로운 발송 요청을 생성합니다. 고객 지원팀이나 시스템 관리자가 발송 실패를 복구할 때 사용됩니다.

Request

HTTP Method: POST
URI: /notifications/email-sends/{send_id}/retry
Headers:
- Authorization: Bearer <access_token>
- Accept: application/json

Response (200)

{
  "data": {
    "id": 1003,
    "original_send_id": 1001,
    "template_id": 1,
    "to_email": "user@example.com",
    "subject": "환영합니다, 홍길동님!",
    "status": "pending",
    "created_at": "2024-01-25T16:00:00Z"
  }
}

5. 에러 코드 정의

이메일 템플릿 관련 에러

TEMPLATE_NOT_FOUND: 템플릿을 찾을 수 없음
TEMPLATE_NAME_DUPLICATE: 중복된 템플릿 이름
INVALID_TEMPLATE_VARIABLES: 잘못된 템플릿 변수 형식
TEMPLATE_IN_USE: 사용 중인 템플릿 삭제 시도

이메일 발송 관련 에러

SEND_NOT_FOUND: 발송 이력을 찾을 수 없음
INVALID_EMAIL_FORMAT: 잘못된 이메일 형식
TEMPLATE_VARIABLES_MISSING: 필수 템플릿 변수 누락
SEND_QUOTA_EXCEEDED: 발송 할당량 초과
RECIPIENT_BLOCKED: 차단된 수신자
BULK_SEND_LIMIT_EXCEEDED: 대량 발송 제한 초과

6. 결론

이메일 알림 시스템의 API는 템플릿 관리와 발송 이력을 분리하여 확장성과 유지보수성을 높였습니다. 주요 특징은 다음과 같습니다:

템플릿 기반 이메일 시스템: 재사용 가능한 템플릿으로 일관성 있는 이메일 발송
변수 치환 기능: 동적 콘텐츠 생성을 위한 템플릿 변수 지원
발송 이력 추적: 모든 이메일 발송에 대한 상세한 로그 관리
대량 발송 지원: 마케팅 이메일 등 대량 발송 기능
에러 처리 및 재시도: 실패한 발송에 대한 재시도 메커니즘

이를 통해 안정적이고 확장 가능한 이메일 알림 서비스를 제공할 수 있습니다.

👇 도움이 되셨다면 👇

PayStream Project

PayStream 알림 연동 우선순위 재정리

알림(Notification) 시스템 API 명세서 및 아키텍처

목차

1. 개요

2. 시스템 아키텍처

3. ERD 구조

4. API 명세서

기본 정보

공통 규칙

공통 에러 응답 포맷

이메일 템플릿 API

1. 템플릿 목록 조회

2. 템플릿 상세 조회

3. 템플릿 생성

4. 템플릿 수정

5. 템플릿 삭제

이메일 발송 API

1. 이메일 발송 이력 조회

2. 발송 이력 상세 조회

3. 이메일 발송 요청

4. 대량 이메일 발송 요청

5. 발송 재시도

5. 에러 코드 정의

이메일 템플릿 관련 에러

이메일 발송 관련 에러

6. 결론