CP-Notify

Email / SMS / Kakao 알림톡 / Push 알림을 단일 API로 보냅니다. provider별 환경변수·서명 처리가 모두 CP 쪽에서 추상화됩니다.

권한

API Key 생성 시 notify.* 권한 활성화 필요. 채널별 권한:

notify.email.send
notify.sms.send
notify.kakao.send
notify.push.send

4채널 공통 사항

채널	Provider	응답 시간 (p50)
Email	Resend	~600ms
SMS	Twilio	~800ms
Kakao	Solapi	~1.2s
Push	Firebase FCM	~400ms

Rate limit (채널별, provider 외부 의존):

채널	한도
Email	200 / min
SMS · Kakao · Push	3000 / min

초과 시 429 Retry-After: 60. 모든 발송 endpoint 는 성공 시 201 Created.

Email 발송 예시

POSThttps://notify.cp-platform.com/notifications/email

인증: API Key
권한: notify.email.send
Rate Limit: 200 / min

your-app/lib/notify.ts

export async function sendWelcomeEmail(email: string) {
  const res = await fetch("https://notify.cp-platform.com/notifications/email", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.CP_NOTIFY_API_KEY!,
    },
    body: JSON.stringify({
      to: email,
      subject: "환영합니다",
      html: "<h1>가입을 축하드립니다</h1>",
    }),
  });
 
  // 201 = 성공, 그 외는 모두 실패 (429 한도 / 403 권한·IDOR / 502 provider 다운)
  if (res.status !== 201) {
    const err = await res.json().catch(() => ({}));
    console.error("[notify]", res.status, err);
    throw new Error(err.detail ?? "이메일 발송 실패");
  }
  return res.json(); // { id, status, channel, created_at }
}

SMS / Kakao / Push

인증 / 응답 형식은 동일, body 만 채널별로 다릅니다. 모두 /notifications/{channel} (suffix 없음).

채널	path	필수 body
SMS	`/notifications/sms`	`to` (E.164 `+8210...`), `text`
Kakao	`/notifications/kakao`	`to` (E.164), `template_id`, `variables`
Push	`/notifications/push`	`title`, `body`, `data?` (수신 device 는 owner_id 의 FCM token 자동)

전체 스키마는 Reference.

비용·할당량

할당량·요금 참고. 발송 전 잔량은 GET /notifications/quotas 로 확인.

보안

API Key 는 절대 클라이언트 노출 금지 — process.env.CP_NOTIFY_API_KEY 처럼 서버 전용
owner_id 기반 IDOR 방어 — body 의 user_id 는 ignored, 발송 대상은 API Key 의 owner_id 로 자동
Kakao template_id 검증 — 본인 채널의 승인 template 만 호출 가능, 그 외 403