📨 크리에이터 아웃리치 발송

크리에이터 핸들 · 금액 · 제품만 입력하면 브랜드 HTML 메일이 완성돼 네이버웍스로 즉시 발송된다. TikTok Shop 크리에이터 섭외용.

dalba-outreach/
├─ index.html            ← 발송 화면 (로그인 + 입력 폼 + 실시간 미리보기)
├─ admin.html            ← 관리자 화면 (팀 전체 현황 · 중복 시도 · 메일함)
├─ email-template.js     ← 메일 템플릿 엔진 (브라우저·서버 공용)
├─ auth.js               ← 직원 계정 목록 · 로그인 세션
├─ history.js            ← 발송 이력 (팀 공용) · 중복 발송 차단
├─ mail.js               ← 네이버웍스 IMAP 읽기
├─ sync.js               ← 메일함 → 이력 변환 (버튼·자동 실행 공용)
├─ reminders.js          ← 회신 없을 때 자동 팔로업(리마인드) 발송
├─ sheets.js             ← 구글시트 읽기 (제품별 매출 상위 영상)
├─ i18n.js               ← 화면 번역 (한국어 · English · Tiếng Việt)
├─ api/
│  ├─ login.js           ← 로그인 (아이디/비번 → 세션 토큰)
│  ├─ outreach-send.js   ← 네이버웍스 SMTP 발송
│  ├─ history.js         ← 겹치는 수신자 미리 확인 · 최근 발송 조회
│  ├─ admin.js           ← 팀 전체 집계 (관리자 전용)
│  ├─ replies.js         ← 받은편지함을 훑어 크리에이터 회신 기록
│  ├─ backfill.js        ← 보낸편지함을 이력으로 가져오기
│  ├─ cron.js            ← 자동 동기화 (Vercel Cron 이 부른다)
│  ├─ products.js        ← TikTok Shop 상품 목록 (썸네일·판매상태)
│  └─ videos.js          ← 제품별 매출 상위 영상 (구글시트)
├─ package.json
└─ vercel.json

email-template.js 는 브라우저 미리보기와 서버 발송이 같은 코드를 쓴다. 템플릿을 두 곳에서 만들면 "미리보기와 실제 메일이 다른" 사고가 나므로 여기 한 곳에서만 만든다.

---

배포 (최초 1회)

1. Vercel → Add New Project → 이 레포 임포트
2. 프레임워크 프리셋 Other, 빌드 설정 변경 없음 (정적 파일 + 서버리스 함수)
3. 아래 환경변수 등록 → Deploy

환경변수

이름	필수	설명
NW_ACCOUNTS	권장	직원 목록. 넣으면 담당자별 로그인 방식으로 동작한다 (아래 참고)
SESSION_SECRET	선택	세션 토큰 서명 키. 없으면 NW_ACCOUNTS 에서 파생 — 이 경우 직원 목록을 고칠 때마다 전원 재로그인
SESSION_DAYS	선택	로그인 유지 기간, 기본 7 일
DASHBOARD_PASSWORD	대체	공용 비밀번호. NW_ACCOUNTS 를 넣으면 쓰이지 않는다 (로그인이 대신함)
NW_DOMAIN	선택	발신 허용 도메인, 콤마 구분. 기본 dalbausa.com,dalba.com
NW_SMTP_HOST	선택	기본 smtp.worksmobile.com
NW_SMTP_PORT	선택	기본 465 (SSL). 587 이면 STARTTLS 로 자동 전환
NW_BCC	선택	발송 사본을 받을 주소 — 팀 공용 발송 이력 보관용
LOGO_URL	선택	메일 헤더 로고 이미지의 공개 절대주소. 없으면 텍스트 워드마크로 그린다
KV_REST_API_URLKV_REST_API_TOKEN	권장	발송 이력 저장소. 중복 발송 차단이 여기에 달려 있다 (아래 참고). Vercel 마켓플레이스가 자동 주입
HISTORY_DAYS	선택	재발송 차단 기간, 기본 90 일
HISTORY_SINCE	선택	메일함에서 이력을 채울 시작일, 기본 2026-05-01
HISTORY_LOG_MAX	선택	발송 이력 보관 상한, 기본 100000 건. 담당자가 많아 더 쌓이면 키운다
CRON_SECRET	권장	자동 동기화(/api/cron)를 아무나 못 부르게 하는 비밀값. Vercel 이 자동으로 헤더에 실어 보낸다
ADMIN_EMAILS	선택	관리자 화면을 볼 수 있는 이메일 여러 명. 콤마·세미콜론·공백·줄바꿈 아무거로 구분해도 된다. 비우면 아무도 관리자가 아니다
NW_IMAP_HOST	선택	기본 imap.worksmobile.com
NW_IMAP_PORT	선택	기본 993 (SSL)

TikTok Shop 상품 선택기를 쓰려면 TTS_* 네 개가, 매출 상위 영상 드롭다운을 쓰려면 GOOGLE_SERVICE_ACCOUNT 가 추가로 필요하다 (아래 참고).

---

담당자별 로그인 (NW_ACCOUNTS)

담당자마다 아이디·비밀번호를 주고, 네이버웍스 앱 비밀번호는 서버에만 둔다. 담당자는 앱 비밀번호를 알 필요가 없고 브라우저에도 남지 않는다.

Vercel 환경변수 NW_ACCOUNTS 에 한 줄에 한 명씩 넣는다:

아이디|로그인비번|표시이름|네이버웍스이메일|앱비밀번호|직함(선택)

hannie|Hann2026!|Hannie|[email protected]|abcd efgh ijkl mnop|Creator Partnerships
quinn|Qu1nnX7!|Quinn|[email protected]|wxyz 1234 5678 9012|Creator Partnerships

• # 로 시작하는 줄과 빈 줄은 무시 → 주석·구분선으로 써도 된다
• 값 안에 | 는 못 쓴다 (로그인 비번에 | 가 필요하면 JSON 형식을 쓸 것 — auth.js 주석 참고)
• 앱 비밀번호는 네이버웍스 로그인 비번이 아니라 설정 > 보안 > 외부 앱 비밀번호 값이다
• 앱 비밀번호의 공백은 있어도 그만 없어도 그만 — 발급 화면에 보이는 대로 붙여넣으면 된다

수정 후 Redeploy 해야 반영된다. 퇴사·교체는 그 줄만 지우면 되고, 줄을 지우는 즉시 그 사람이 갖고 있던 세션 토큰도 무효가 된다.

이 방식이 주는 것

• 담당자 10명이든 30명이든 환경변수 한 개만 관리한다
• 발송은 항상 로그인한 사람 계정으로 나간다 — 요청 본문이 다른 주소를 지정해도 무시
• 앱 비밀번호가 브라우저·응답 어디에도 나가지 않는다
• 누가 무엇을 보냈는지 From 으로 구분되고, 답장도 그 사람에게 간다

로그인을 안 쓰는 배포 (BYO)

NW_ACCOUNTS 를 비워두면 예전 방식으로 동작한다 — 담당자가 자기 네이버웍스 주소와 앱 비밀번호를 자기 브라우저에 등록하고, 그 자격증명이 요청마다 함께 온다. 이때는 DASHBOARD_PASSWORD 로 화면을 막고, 발신 주소는 NW_DOMAIN 회사 도메인만 허용한다. 자격증명은 서버에 저장하지 않는다.

---

중복 발송 차단

현재 기본값: 담당자끼리 중복 차단은 꺼져 있다. 다른 담당자가 이미 보낸 크리에이터여도 그대로 발송된다 (발송 화면엔 "ℹ️ 다른 담당자 발송 있음" 참고 표시만). 계속 막히는 것은 🤝 협업 중(관리자·본인 발송 이력 제외), ⛔ 반송 주소 · 🚫 수신 거부, 같은 담당자가 30분 안에 같은 크리에이터에게 다시 보내기(시간 초과 뒤 재시도 중복 방지). 아래의 담당자끼리 차단을 다시 켜려면 Vercel 환경변수 DEDUP_ACROSS_STAFF=1.

담당자가 10명이면 명단이 겹치는 건 시간 문제다. 같은 크리에이터가 d'Alba 메일을 두세 번 받으면 브랜드 인상에 바로 흠이 나므로, 발송 직전에 팀 공용 이력을 확인하고 이미 보낸 사람은 그 건만 보류한다.

• 기본 차단 기간 90일 (HISTORY_DAYS 로 변경)
• 이메일과 TikTok 핸들 둘 다로 판정 — 주소가 달라도 같은 크리에이터면 잡는다
• [email protected] 은 [email protected] 과 같은 편지함으로 본다
• 명단을 붙여넣는 즉시 화면에 ⏸ 보류 표시 + 누가 언제 보냈는지 표시
• 겹치는 사람만 빠지고 나머지는 그대로 발송된다
• 강제 발송(중복 무시)은 관리자만 할 수 있다. 관리자 화면에만 [강제 발송] 체크박스가 뜨고, 그 외 담당자는 중복이 자동 보류되어 관리자 페이지의 ⏸ 중복 시도에 남는다. 화면에서 숨기는 것만으로 끝내지 않고 서버가 관리자가 아니면 force 를 무시한다.
• 발송이 실패하면 자리를 반납한다 — 실패한 주소가 90일간 막히지 않도록

두 명이 같은 사람에게 동시에 누르는 경합은 조회로는 못 막는다(둘 다 "없음"을 본다). 그래서 조회가 아니라 SET NX(없을 때만 쓰기)로 자리를 먼저 잡고 보낸다.

저장소 붙이기 (한 번)

1. Vercel → dalba-outreach → Storage → Create Database → Upstash Redis
2. 프로젝트에 연결(Connect)하면 KV_REST_API_URL / KV_REST_API_TOKEN 이 자동으로 들어간다
3. Redeploy

무료 티어로 충분하다. 발송 1건당 명령 23개, 미리 확인은 명단 1명당 12개다.

📥 지난 발송 가져오기 (보낸편지함 → 이력)

이 도구를 쓰기 전에 나간 메일도 중복 판정에 들어와야 한다. 안 그러면 툴을 켠 날 이전에 접촉한 크리에이터에게 그대로 다시 나간다. 관리자 화면의 [📥 지난 발송 가져오기] 탭에서 담당자별로 보낸편지함을 읽어 넣는다.

• 미리보기가 먼저다. 보낸편지함에는 아웃리치가 아닌 메일이 섞여 있고, 그대로 밀어 넣으면 동료·거래처 주소가 크리에이터로 잡혀 앞으로 그 주소로 발송이 막힌다. 무엇이 들어갈지 확인한 뒤에만 쓰이고, 조건을 바꾸면 미리보기를 다시 해야 한다
• 자동으로 거르는 것 — 사내 도메인 수신자(내부 메일), 수신자 6명 이상(공지·회람). 제목 포함 문구를 넣으면 그 문구가 든 메일만 (예: Collab)
• 차단 기간은 실제 보낸 날짜 기준으로 남은 만큼만 건다. 120일 전 메일을 지금부터 90일 막아 버리면 안 되기 때문. 이미 지난 건은 기록으로만 남는다
• 같은 메일을 두 번 넣지 않는다(messageId 로 판별). 여러 번 돌려도 안전하다
• 도구로 보낸 정확한 기록이 있으면 덮어쓰지 않는다

⚠️ 저장소를 아예 설정하지 않으면 이 기능은 조용히 꺼지고 발송은 예전처럼 된다. 반대로 설정은 했는데 저장소가 죽으면 중복인지 알 수 없으므로 보내지 않는다. 이때는 강제 발송이 유일한 탈출구다 — 켜 놓고 조용히 중복이 나가는 게 가장 나쁜 결과라서. 관리자가 아닌 담당자는 이 경우 보내지 못하고 보류로 남는다.

---

📊 관리자 화면 (/admin.html)

ADMIN_EMAILS 에 등록된 사람만 볼 수 있다 — 여러 명을 콤마·세미콜론·공백·줄바꿈 아무거로 구분해 넣으면 된다 (예: [email protected], [email protected]). 발송 화면과 같은 로그인을 쓰므로 두 번 로그인하지 않아도 되고, 관리자에게만 발송 화면 헤더에 바로가기가 뜬다.

관리자 본인은 집계에서 빠진다. 관리자는 감시하는 쪽이라 담당자 실적 대상이 아니다. ADMIN_EMAILS 에 있는 사람은 담당자별·일별·발송 이력·대화·명단 어디에도 나오지 않는다 (관리자이자 담당자로 등록된 사람도 마찬가지). 실적을 봐야 하는 담당자는 NW_ACCOUNTS 에는 있고 ADMIN_EMAILS 에는 없어야 한다.

탭	보이는 것
담당자별	누가 몇 건 보냈는지 · 회신·회신율 · 중복으로 막힌 횟수 · 마지막 발송
📈 일별	날짜별 발송·회신 건수 (막대) + 담당자별 내역. 담당자·기간으로 거르기
🗂 내 파이프라인	개인용 칸반. 내가 접촉한 크리에이터를 단계별로: 첫 발송 → 1차 리마인드 → 2차+ 리마인드 → 1차 회신 → 2차+ 회신. 카드를 누르면 대화가 열린다
💬 대화	담당자별로 회신한 크리에이터 목록 → 누르면 협상 스레드를 본문까지 (아래 참고)
발송 이력	시각·수신자·핸들·캠페인·담당자. 담당자/기간/검색어로 거르기
⏸ 중복 시도	보내려다 막힌 시도. 누가 누구에게 시도했고 원래 누가 보냈는지

🗂 내 파이프라인 — 개인 진행 상황을 한눈에

내가 접촉한 크리에이터를 단계별로 칸반으로 보여준다: 첫 발송(회신 대기) → 1차 리마인드 보냄 → 2차+ 리마인드 보냄 → 1차 회신 → 2차+ 회신(협상). 카드를 누르면 그 사람과의 대화가 열린다.

• 개인용 — 기본은 로그인한 본인이 접촉한 크리에이터만. (담당자 선택칸에서 다른 사람을 고르면 그 사람 파이프라인을 볼 수도 있다.)
• 팀 집계는 관리자를 빼지만, 이 화면은 예외다 — 본인이 관리자여도 자기 파이프라인은 봐야 하므로 관리자 제외 필터를 적용하지 않는다.
• 단계는 자동 판정한다: 회신이 있으면 회신 단계(1=1차, 2+=협상), 회신이 없으면 보낸 리마인드 횟수(0=첫 발송, 1=1차 리마인드, 2+=2차 리마인드). 리마인드는 회신 없는 사람에게만 나가므로, 리마인드 단계는 "회신 대기" 를 세분한 것이다. 카드에 리마인드 배지도 뜬다.
• 수동으로 옮기는 CRM 이 아니라 실제 발송·회신·리마인드 데이터에서 그대로 만든다.

💬 대화 — 담당자가 네고·협상을 잘 하고 있는지

관리자가 담당자 ↔ 크리에이터 대화를 본문까지 열어 본다. 목록은 회신한 크리에이터만 뜨고(협상은 회신이 있어야 성립), 한 명을 누르면 그 담당자 메일함에서 주고받은 메일을 시간순 채팅으로 보여준다 — 담당자가 보낸 것(오른쪽)과 크리에이터 회신(왼쪽) 양쪽 다.

지켜지는 선:

• 관리자만. ADMIN_EMAILS 밖의 담당자는 이 경로로도 남의 메일함을 못 본다. 접근 통제는 이 하나다.
• 담당자 계정은 크리에이터 아웃리치 전용이라 개인·사내 메일이 없다 — 그래서 peer 를 회신 기록으로 재검증하지 않는다(그 검증이 회신 주소가 미묘하게 다를 때 정당한 대화를 막곤 했다).
• 본문은 저장하지 않는다. 열 때만 그때그때 IMAP 으로 받아 보여주고, 그 담당자와 그 한 명 사이 메일만 받는다(받은편지함 전체가 아니다). 본문 파싱은 mailparser 를 쓴다.
• 목록은 회신한 크리에이터만. 발송만 하고 회신이 없는 건은 대화로 뜨지 않는다.
• API: GET /api/thread?staff=<담당자>&peer=<크리에이터> (관리자 전용).

회신 집계는 눌러야 갱신된다

서버리스에는 상주 프로세스가 없어 회신이 자동으로 세어지지 않는다. 담당자별 화면의 [📥 회신 수집] 을 누르면 전원의 받은편지함을 훑어 우리가 보낸 적 있는 주소에서 온 메일만 기록한다. 화면을 열 때마다 IMAP 을 뒤지면 담당자가 10명일 때 못 견디므로, 세어서 남겨 두고 집계는 그 기록만 읽는다.

• 같은 메일을 두 번 세지 않는다(messageId 로 판별) — 여러 번 눌러도 안전하다
• 회신은 보낸 담당자 앞으로 달린다. 누구의 아웃리치가 답을 받았는지가 성과이므로
• 회신율의 분자는 "답장한 크리에이터 수" 다. 답장 통수로 세면 한 사람이 세 번 답할 때 3건이 되어 회신율이 100% 를 넘는다. (그날 몇 통 왔는지는 일별 화면이 통수로 보여준다)
• 내용은 보지 않는다. 부재중 자동응답도, "관심 없습니다" 도 회신 1로 센다 — "답이 왔는가" 까지만 아는 지표다
• 크리에이터가 우리가 보낸 주소가 아닌 다른 주소로 답하면 잡히지 않는다
• 일별에서는 받은 날에 센다 — 언제 보냈는지가 아니라 언제 답이 왔는지가 궁금한 것
• 60초 안에 전원을 못 훑으면 거기까지만 하고 남은 인원을 알려준다. 다시 누르면 이어진다
• 주기 실행이 필요하면 Vercel Cron 으로 POST /api/replies 를 부르면 된다

일별 차트에서 조심할 것

기록의 시각은 UTC 다. 한국에서 아침 8시에 보낸 건 UTC 로는 전날 23시라, 그대로 날짜를 자르면 하루씩 밀린다. 그래서 브라우저가 tz(분 단위 시차)를 보내고 서버가 그만큼 옮겨서 자른다. 발송이 없던 날도 0 으로 채운다 — 빈 날을 빼면 막대가 다닥다닥 붙어 "매일 꾸준히 보낸 것" 처럼 보이기 때문이다.

중복 시도 탭이 이 화면의 핵심이다. 같은 크리에이터가 자주 걸린다면 명단 배분을 고쳐야 한다는 신호이고, 그 신호는 다른 곳에서는 보이지 않는다.

만 단위 이력도 다 집계된다

발송 이력은 최대 10만 건(HISTORY_LOG_MAX)까지 보관한다. 담당자가 10명이면 몇 달치가 쉽게 만 단위를 넘는데, 집계(담당자별·일별·요약)는 저장된 전부를 읽어 센다. 저장소에서 값을 내려받을 때는 큰 리스트가 REST 응답을 터뜨리지 않도록 청크로 나눠 받고, 실제 쌓인 만큼만(LLEN) 읽어 멈춘다. 발송 이력·중복·회신 목록 탭은 화면 표시만 개수로 끊고(limit, 기본 1,000), 상한에 걸리면 화면에 "잘렸음" 을 알린다 — 집계 숫자는 목록 표시 개수와 무관하게 항상 전체 기준이다.

⚠️ 권한은 반드시 환경변수로 명시한다

ADMIN_EMAILS 가 비어 있으면 아무도 관리자가 아니다(화면이 열리지 않는다). 관리자 판정을 코드에 숨겨 두면 나중에 이 배포를 보는 사람이 권한 범위를 알 수 없기 때문에, 일부러 "설정하지 않으면 닫힘" 으로 만들었다.

---

🔄 메일함에서 동기화

담당자별 화면의 [🔄 메일함에서 동기화] 하나로 두 가지를 채운다.

1. 보낸편지함 → 발송 이력 — 2026-05-01 이후 보낸 메일을 이력에 넣는다
2. 받은편지함 → 회신 기록 — 그중 우리가 보낸 적 있는 주소에서 온 메일만

발송에 쓰는 그 외부 앱 비밀번호가 IMAP 에도 그대로 통한다. 새로 등록할 것은 없다.

• 제목·발신자·수신자만 읽는다 — 본문은 가져오지 않는다(envelope 만 fetch)
• 전원을 한 요청에 몰면 함수 제한시간(60초)을 넘기므로 한 사람씩 나눠서 부르고 진행 상황을 그때그때 보여준다 — 오래 걸리는 작업이 말없이 도는 게 제일 나쁘다
• 같은 메일을 두 번 넣지 않는다(messageId 로 판별). 여러 번 눌러도 안전하다
• 보낸편지함 이름은 계정마다 다르므로(Sent / 보낸메일함 …) IMAP 의 용도 플래그(\Sent) 로 찾고, 없을 때만 이름으로 추측한다 — 이름 목록에 의존하면 어느 계정에서 조용히 빈 목록이 된다

⚠️ 보낸편지함에는 아웃리치가 아닌 메일이 섞여 있다

그대로 밀어 넣으면 동료·거래처 주소가 크리에이터로 잡히고, 그 주소로는 앞으로 발송이 막힌다. 그래서 사내 도메인(NW_DOMAIN) 수신자와 수신자 6명 이상(공지·회람)은 자동으로 거른다. 그래도 섞이는 게 있으면 POST /api/backfill 에 subject 를 주어 좁힐 수 있다.

⚠️ 관리자센터에서 IMAP/POP3 사용 허용이 켜져 있어야 한다 (SMTP 와 같은 설정 화면).

⏰ 자동 실행

vercel.json 의 crons 가 15분마다 /api/cron 을 부른다 (Pro 플랜 기준 — Hobby 는 하루 1회로 제한되므로 그때는 0 22 * * * 같은 하루 1회 스케줄로 바꿔야 한다). 매 실행은 ① 예약 발송(기한이 된 것 — 시각 약속이라 가장 먼저) ② 메일함 동기화 ③ 자동 리마인드 순서로 처리한다.

• 함수 제한시간(60초)은 담당자 10명의 메일함 20개를 열기엔 짧다. 그래서 커서를 저장해 이어서 돈다 — 한 번에 도는 만큼만 처리하고 다음 실행이 그 다음 사람부터 이어받는다
• 마지막 실행 시각은 담당자별 화면에 표시된다. 숫자가 낡았는지 화면에서 바로 알아야 하므로
• CRON_SECRET 을 설정하면 그 값을 가진 요청만 부를 수 있다 (Vercel 이 자동으로 실어 보낸다). 로그인한 관리자도 /api/cron 을 직접 열어 상태를 확인할 수 있다

---

🔎 중복 검사 (발송 화면 탭)

발송 화면 상단 [🔎 중복 검사] 탭에서 크리에이터 핸들 또는 이메일을 넣으면, 전체 담당자 (관리자 포함) 의 발송 이력에서 그 사람에게 보낸 적이 있는지 · 누가 · 언제 보냈는지를 찾아 준다.

• api/lookup.js 가 공용 발송 로그(+회신 로그)를 훑어 그 크리에이터에게 간 모든 발송을 모은다 (예약 키와 달리 "누가누가 보냈나" 를 전부 보여준다). 관리자 발송도 빼지 않는다.
• 이메일이면 이메일 기준, 아니면 핸들 기준으로 매칭한다(plus 주소·@ 유무 정규화).
• 발송 화면의 즉석 중복 확인과 목적이 다르다: 그건 "지금 이 명단이 겹치나", 이건 "이 한 명을 누가 접촉했나" 를 조율·확인하는 도구. 로그인한 담당자면 누구나 쓸 수 있다.

---

⏰ 예약 발송 (크리에이터 현지 시간)

발송 화면에서 [나중에 보내기] 를 켜면 시간대·날짜·시각을 골라 예약한다. 미국 크리에이터에게는 미국이 활발한 시간, 영국은 영국 시간에 맞춰 보내기 위한 것 — 고른 시간대의 현지 시각 기준이다.

• 시간대 변환(서머타임 포함)은 서버가 한다 (api/schedule.js — Intl 시간대 규칙 사용)
• 크론이 15분마다 돌므로 실제 발송은 예약 시각에서 최대 15분 안이다
• 캠페인 전문이 스냅샷으로 저장된다 — 예약 후 폼을 바꿔도 예약분은 안 바뀐다
• 발송은 즉시 발송과 같은 코드(send-core.js)라 중복 차단·자동 리마인드·CC·첨부가 똑같이 적용된다
• 수백 명 예약은 크론 예산만큼 보내고 남은 수신자를 되써서 다음 실행이 이어받는다
• 예약 목록·취소는 발송 화면 아래에서. 본인 것만 취소할 수 있다(관리자는 전체)
• 로그인(계정) 방식 + 이력 저장소가 있어야 동작한다 — 예약 시각에 서버가 대신 보내려면 앱 비밀번호(NW_ACCOUNTS)가 서버에 있어야 하기 때문

---

⏳ 자동 리마인드 (회신 없을 때 팔로업)

발송 화면에서 [회신 없으면 자동 리마인드] 를 켜면, 그 발송에 대해 며칠마다·최대 몇 번 팔로업을 보낼지 담당자가 직접 정한다(기본 3일마다·최대 2번). 회신이 오면 즉시 멈춘다.

• 켤 때 발송마다 예약이 저장된다(outreach:reminders HASH — 담당자+크리에이터 한 쌍당 하나).
• 자동 동기화(/api/cron)가 메일함을 훑어 회신을 갱신한 뒤 기한이 된 예약을 처리한다. · 회신했으면 → 멈춤 · 정한 횟수를 다 채웠으면 → 멈춤 · 담당자가 명단에서 빠졌으면 → 멈춤
• 리마인드 본문은 원 메일에 대한 짧은 팔로업이다(같은 제목에 Re:). 긴 제안을 다시 보내지 않는다 — 짧은 넛지가 회신율이 더 높고 스팸처럼 보이지 않는다. 헤더 로고·서명·"no thanks 면 그만" 안내는 그대로 붙는다.
• 이력 저장소(Upstash)가 있어야 동작한다(예약을 저장할 곳이 필요). 없으면 체크박스가 안 뜬다.
• 관리자 페이지 상단에 리마인드 N건 발송 / 회신으로 M건 종료 가 요약으로 뜬다.

크론이 15분마다 돌므로 "3일마다" 는 예약 시각 이후 첫 크론(최대 15분 안)에 나간다. Hobby 플랜으로 내리면 크론이 하루 1회라 리마인드도 하루 한 번만 처리된다.

---

네이버웍스 설정 (⚠️ POP3 아니라 SMTP)

POP3/IMAP은 메일을 받는 프로토콜이고, 프로그램이 보내려면 SMTP 인증이 필요하다. Gmail 연동·Gmail API는 불필요 — 웍스 SMTP 위에 한 겹 더 얹는 것이라 단계만 늘어난다.

항목	값
SMTP 서버	smtp.worksmobile.com
포트	465 (SSL) — 587(STARTTLS)도 지원
아이디	네이버웍스 이메일 전체 (예: [email protected])
비밀번호	로그인 비번 ❌ → 외부 앱 비밀번호 ⭕

1. 조직 관리자 (1회) — 관리자센터에서 IMAP/POP3·SMTP 사용 허용 → 안 켜면 담당자 개인 설정에 메뉴 자체가 안 뜬다
2. 담당자 각자 (1회) — 네이버웍스 설정 > 보안 > 외부 앱 비밀번호 에서 발급
3. 발급받은 값을 관리자가 NW_ACCOUNTS 에 등록 → 담당자는 아이디/비번으로 로그인만 하면 끝 (로그인을 안 쓰는 배포라면 화면 오른쪽 위 [내 발신 계정] 에 직접 입력)

발송 한도

계정당 24시간 20,000 수신자, 분당 60회. To/Cc/Bcc 모두 카운트되고 PC웹·모바일·SMTP·API 가 합산된다. 초과 시 각각 최대 1시간 / 1분 차단.

담당자가 10명 넘어도 되는 이유

사람마다 환경변수를 따로 두면 입사할 때마다 Vercel 설정 + 재배포가 필요해 확장이 안 된다. 그래서 NW_ACCOUNTS 한 개에 줄만 추가하는 방식을 쓴다 (위 담당자별 로그인).

• 각자 자기 주소로 발송되고 답장도 자기에게 온다 (Reply-To 동일)
• 한도(24시간 20,000건)는 계정별로 잡히므로 사람이 늘수록 총 발송량도 늘어난다
• ⚠️ 네이버웍스는 인증 계정 외 주소를 From 으로 지정할 수 없다. 그래서 발신자는 항상 인증 계정으로 강제되고, 요청이 다른 주소를 보내와도 무시한다

오픈 릴레이 방지 3겹 — ① SMTP 호스트/포트는 서버 고정(요청으로 변경 불가) ② 발신자는 로그인 세션에서 확정 (BYO 배포에서는 NW_DOMAIN 회사 도메인만 허용) ③ 로그인 없이는 발송 API 자체가 401

---

모바일 · PC 양쪽에서 보이기

크리에이터는 대부분 폰으로 메일을 연다. 그래서 폭을 두 겹으로 맞춘다.

1. 틀 자체가 유동 — 바깥 표가 width:100% + max-width:600px 다. 예전에는 width="600" 이 박혀 있어서 좁은 화면에서 잘렸다. 표의 width 속성은 max-width 를 모르는 클라이언트에서 그대로 이겨 버린다.
2. 미디어 쿼리는 보정만 — 620px 아래에서 여백·글자 크기를 줄이고 버튼을 가로로 채운다. 지원하지 않는 클라이언트가 아직 있으므로, 이 CSS 가 통째로 무시돼도 이미 화면에 들어와야 한다.

Outlook 데스크톱(Word 엔진)은 max-width 를 무시해 본문이 창 너비만큼 늘어난다. 그래서 MSO 전용 주석으로 600px 고정 표를 하나 더 감쌌다(고스트 테이블).

검증: 320 / 360 / 393 / 768 / 1280px 에서 가로 넘침 0, <style> 를 통째로 지운 상태에서도 320px 통과.

화면 오른쪽 미리보기 위의 [📱 모바일] 을 누르면 390px 폭으로 좁혀 보인다. 메일 안의 미디어 쿼리가 iframe 폭에 반응하므로 실제 폰에서 보이는 그대로다.

---

메일 구성

헤더(달바 로고·캠페인 배지·제목) → 인사 → 브랜드 소개 → 개인화 한 줄 → 💰금액 / 📈커미션 → 📦협업 상세 → 🧴제품(이미지·설명·링크) → 🔥바이럴 영상 최대 4개 → 📋Next steps → CTA 버튼 → 서명

• 브랜드 컬러 — 헤더는 배너와 같은 노랑→크림 그라데이션에 검정 로고다. 그라데이션을 못 읽는 클라이언트(Outlook 등)는 단색 노랑으로 떨어져도 브랜드에 맞다. 본문은 흰 카드 + 따뜻한 크림 박스, 강조는 앰버, CTA 는 검정 버튼.

• 로고 — 기본은 실제 로고를 본뜬 세리프 d'Alba + piedmont **워드마크(텍스트)**라 어떤 클라이언트에서도 반드시 보인다. 실제 이미지 로고는 레포의 logo-black.png(검정 워드마크·투명배경)를 쓴다. 메일 안에 인라인(cid)으로 박아 넣는다 — 외부 URL 로 불러오면 배포 보호·리다이렉트· 전파 지연 등으로 그 요청이 실패해 로고가 깨질 때가 있는데, 파일을 메일에 담으면 외부 요청이 아예 없어 깨지지 않는다(제품 이미지 첨부와 같은 방식). 미리보기도 같은 파일을 data URL 로 그려 외부 요청이 없다. 이미지를 아예 꺼둔 수신자에게는 alt 로 브랜드명이 뜬다. 다른 도메인·CDN 을 쓰려면 LOGO_URL 에 공개 절대주소를 넣으면 인라인 대신 그 URL 을 쓴다.

• 협업 유형 3종: 유상 / 어필리에이트 / 유상+어필리에이트(합산 문구 자동 추가). 후불제 — "선불(up front)" 이 아니라 "콘텐츠 게시·승인 후 지급" 으로 문구를 맞췄다

• 제품 이미지 — URL 직링크를 넣거나, 상품이 TikTok Shop 목록에 없으면 파일을 첨부한다. 첨부한 이미지는 브라우저에서 최대 1000px 로 줄여 JPEG 로 다시 인코딩(요청 본문·발송 속도 보호)한 뒤 메일에 인라인(cid) 첨부로 담긴다 — 외부 링크가 아니라 메일 안에 들어가므로 링크 없이도 보인다. URL 과 첨부가 둘 다 있으면 첨부가 우선

• Next steps — 크리에이터가 답장에 무엇을 담아야 하는지 번호로 제시. 4줄까지 화면에서 편집하고 빈 칸은 자동으로 빠진다. 전부 비우면 섹션째 사라짐. 기본값은 ①관심 회신 ②WhatsApp/선호 연락처

• 개인화 변수 — 제목·본문 어디서나 {{name}} {{handle}} {{brand}} {{campaign}} {{product}} {{amount}} {{commission}}

• <table> + 인라인 CSS — Gmail·네이버웍스 웹에서 레이아웃이 깨지지 않음. 플레인 텍스트 대체본을 함께 만들어 스팸 점수를 낮춘다

• 통화는 기본 USD. KRW·GBP·EUR·JPY 선택 가능 (통화 기호 대신 USD 500 처럼 코드로 표기 — ₩ 의 가로 이중선이 숫자에 취소선처럼 겹쳐 보임)

🛍 TikTok Shop 상품 선택기

제품 칸 위의 [TikTok Shop에서 선택] 버튼을 누르면 썸네일 그리드가 뜨고, 상품을 클릭하면 제품명 · 이미지 URL · 제품 링크가 한 번에 채워진다.

• 판매중(ACTIVATE)만 기본 표시. 체크박스로 전체 보기 전환
• 상품명 · 상품 ID 둘 다로 검색. 카드마다 상품 ID 가 함께 보인다
• 목록에 없는 ID 를 치면 그 ID 하나만 서버에 직접 조회한다 — 판매중지 상품이나 목록 상한(1,000개) 밖의 상품도 이렇게 집어올 수 있다
• 가격·재고 표시, 품절 표시
• 썸네일은 .webp → .jpeg 로 바꿔 내보낸다 (Outlook 등이 webp 를 렌더링하지 못함)
• 환경변수가 없으면 버튼 자체가 나타나지 않는다 — 상품 선택은 편의 기능이라 자격증명 없이도 나머지 기능은 그대로 동작해야 하기 때문

환경변수 (전부 필요)

이름	어디서
TTS_APP_KEY	Partner Center → Manage apps → App key
TTS_APP_SECRET	같은 화면 → App secret
TTS_SHOP_CIPHER	샵별 식별자
TTS_REFRESH_TOKEN	샵 Authorize 후 /api/v2/token/get 으로 발급

액세스 토큰은 저장하지 않는다. 서버리스라 디스크에 쓸 수 없으므로 refresh token 으로 필요할 때 발급받아 메모리에만 두고, 만료 5분 전 선제 갱신 + 105002 응답 시 1회 재시도한다.

⚠️ refresh token 을 dalba-check 와 공유하면, TikTok 이 갱신 때마다 새 refresh token 을 발급하는 정책일 경우 한쪽이 갱신했을 때 다른 쪽이 만료될 수 있다. 인증 오류가 반복되면 앱을 하나 더 만들어 토큰을 분리하는 것이 정석이다.

진단

• GET /api/products?debug=1 — 원본 응답의 필드 구조를 함께 반환
• GET /api/products?all=1 — 판매중이 아닌 상품까지 포함
• GET /api/products?id=<상품ID> — 그 상품 하나만 (목록을 거치지 않는다)
• GET /api/products?fresh=1 — 10분 캐시 무시

⚠️ 페이지네이션 주의 — products/search 의 page_token 은 쿼리 파라미터다. 본문에 넣으면 API 가 조용히 무시하고 매번 1페이지를 돌려주므로, 같은 상품이 두 번 나오고 100번째 뒤 상품은 영영 안 보인다. 그래서 응답의 total 이 실제 상품 수와 맞는지가 이 엔드포인트의 첫 번째 점검 항목이다 (id 기준 중복 제거도 함께 걸어 뒀다).

왜 CRUVA 가 아니라 TikTok Shop 원본 API 인가: CRUVA 응답에는 상품 이미지 필드가 없고, 상태도 문서화되지 않은 숫자 코드(1/3/4/6)로만 온다. 상품 페이지에서 og:image 를 긁는 우회로는 연속 요청 시 CAPTCHA 가 떠서 쓸 수 없다. 원본 API 는 main_images 와 문자열 status 를 함께 주므로 두 문제가 한 번에 풀린다.

🔥 매출 상위 영상 드롭다운

상품을 고르면 그 제품ID(pid)로 실제 매출이 난 영상이 매출순 드롭다운으로 뜬다. 누르면 바이럴 영상 칸에 URL 과 @핸들 · GMV $12,345 라벨이 함께 채워진다.

출처는 TikTok Shop API 가 아니라 구글시트다 — 그 집계는 이미 영상성과_신API테스트 탭에 매일 쌓이고 있어서, 같은 API 를 두 번 부를 이유가 없다. 읽는 열은 F(핸들) · H(GMV) · M(영상ID) · O(제품ID) 네 개뿐이다.

• 매출 1 이상만 후보. 같은 영상이 여러 줄로 들어오면 영상ID 로 묶어 최댓값만 남긴다
• 시트는 하루 한 번 갱신되므로 서버에서 30분 캐시
• 시트 전체가 크므로 F:O 범위만 받아온다 (통째로 받으면 함수 시간·메모리를 넘긴다)
• 상품을 안 골랐거나 그 pid 의 영상이 없으면 드롭다운은 나타나지 않는다

환경변수

이름	기본값 / 설명
GOOGLE_SERVICE_ACCOUNT	서비스 계정 JSON 통째로. 시트를 그 계정 이메일에 뷰어로 공유해야 한다
SHEET_ID	1_qkd6LZ1wFoihhJSuYdabQ4iRbx-jsFYVxeGIoEb-_g
SHEET_TAB	영상성과_신API테스트
SHEET_CSV_URL	(대안) 웹에 게시한 CSV 주소

⚠️ SHEET_CSV_URL 은 설정이 제일 쉽지만 주소를 아는 사람은 누구나 볼 수 있다. 크리에이터 핸들과 매출이 담긴 표라서, 시트를 비공개로 두는 서비스 계정 쪽을 권장한다. 서비스 계정 JSON 에는 개인키가 들어 있다 — Vercel 환경변수에만 넣고 레포에 커밋하지 말 것.

GET /api/videos?probe=1 로 설정 여부만 먼저 확인할 수 있다.

---

🌐 화면 언어 (한국어 · English · Tiếng Việt)

헤더 오른쪽 KO / EN / VI 버튼으로 바꾼다. 선택은 브라우저에 저장되고, 처음 여는 사람은 브라우저 언어를 따라 자동으로 맞춰진다.

번역은 i18n.js 가 그려진 뒤의 DOM 을 훑어 바꾸는 방식이다. 화면을 그리는 코드는 하나도 건드리지 않았고, MutationObserver 가 붙어 있어 나중에 추가되는 문구도 자동으로 잡힌다. 사전의 키는 한국어 원문 그대로다 — 번역이 없으면 한국어가 그대로 남지, 화면이 비지는 않는다.

주의할 점 세 가지 (전부 실제로 밟았던 함정):

• 숫자·이메일은 {n} {e} 로 가려 두고 번역 후 되돌린다. 안 그러면 사전 키가 값마다 달라진다
• setAttribute 는 값이 같아도 변경 기록을 남긴다 → 옵저버가 다시 돌아 무한 루프. 모든 쓰기 앞에 같은 값인지 비교를 건다
• 언어 버튼 자체는 번역 대상에서 뺀다(.langs). 안 그러면 EN 화면에서 "한국어" 버튼이 사라진다

메일 본문은 번역되지 않는다. 화면 UI 만이다. 크리에이터에게 나가는 메일 문구는 담당자가 직접 쓰는 값이라 자동 번역 대상이 아니다.

담당자마다 제품이 다른 경우

폼에 입력한 캠페인·제품·영상·Next steps 는 그 사람 브라우저에 자동 저장되어 다음에 열면 그대로 남아 있다. 한 번만 세팅하면 이후엔 크리에이터 정보만 넣으면 된다.

반면 수신자별 값(이름·핸들·이메일·개인화 한 줄)은 일부러 저장하지 않는다 — 앞사람 내용이 다음 사람에게 잘못 나가는 것이 이 툴에서 가장 위험한 사고이기 때문.

---

대량 발송

구글시트에서 헤더 포함 복사 → 붙여넣기. 탭(시트)·콤마(CSV) 모두 인식.

인식 열	의미
email (필수)	수신 주소
name · handle	이름 / 틱톡 핸들
amount · commission	있으면 공통 조건보다 우선 (사람마다 다른 단가)
whyYou	개인화 한 줄

• 헤더 표기가 흔들려도 인식한다 (E-Mail, Email Address, Creator Name, TikTok Handle, 한글 헤더 등)
• 이메일 형식 오류·중복 주소는 자동 제외하고 사유를 표에 표시
• 한 요청당 25명씩 끊어 순차 전송(Vercel 60초 제한) + 진행률 표시, 통당 0.4초 간격
• 실패한 수신자는 사유와 함께 따로 표시 — 한 건 실패해도 나머지는 계속 발송

---

API

요청	동작
GET /api/login	이 배포의 인증 방식(accounts / byo)·세션 기간·등록 인원 수. 아이디 목록은 알려주지 않음
POST /api/login	{ id, pw } → { token, user }. 실패 메시지는 아이디·비번을 구분하지 않음
GET /api/outreach-send	설정 상태 조회 (SMTP 호스트·허용 도메인·배치 상한·로그인한 사람). 비밀번호류는 반환하지 않음
POST /api/outreach-send	발송. { campaign, recipients[] } — 로그인 방식에서는 auth 불필요
POST + force: true	이미 보낸 사람에게도 발송 (중복 차단 무시). 관리자만 유효 — 아니면 서버가 무시
POST + dryRun: true	발송 없이 렌더 결과(제목·HTML)만 반환
GET /api/history	중복 차단이 켜져 있는지 · 차단 기간
GET /api/history?recent=200	최근 발송 기록 (누가·언제·누구에게)
POST /api/history	{ recipients[] } 중 겹치는 사람 미리 확인
GET /api/admin	담당자별 집계 (관리자 전용)
POST /api/replies	받은편지함을 훑어 회신 기록. all:true 는 관리자만(전원)
GET /api/admin?view=replies	회신 기록 (담당자·검색어로 거르기)
GET /api/admin?view=daily&tz=-540	일별 발송 건수. tz 는 브라우저 시차(분) — 없으면 UTC 기준이라 날짜가 밀린다
GET /api/admin?view=people|sent|blocked	크리에이터별 / 발송 이력 / 중복 시도. by q days limit 로 거르기
POST /api/backfill	보낸편지함 → 발송 이력. since 기본 2026-05-01, dryRun:true(기본)면 미리보기만
GET /api/products	판매중 상품 목록 (썸네일·가격·재고)
GET /api/products?probe=1	자격증명 설정 여부만 확인 (상품 조회 안 함)
GET /api/videos?pid=<상품ID>	그 제품의 매출 상위 영상 (핸들·GMV·영상ID·URL). limit 기본 20
GET /api/videos?probe=1

/api/login 을 뺀 나머지는 인증이 필요하다 — 로그인 방식은 Authorization: Bearer <token>, BYO 방식은 x-dashboard-password: <비번>.

---

🌿 브랜드 탭 (d'Alba · Veganery)

발송 화면의 ✉️ 발송은 d'Alba(노랑), 🌿 Veganery 발송은 비거너리 by d'Alba(연두~초록) 메일이다.

• 탭을 누르면 메일 로고(logo-black.png ↔ logo-veganery.png)와 색상이 바뀐다 — 미리보기·실제 발송·자동 리마인드·예약 발송 모두 같은 테마
• 작성 내용(초안)·명단·첨부 제품 이미지는 브랜드별로 따로 저장된다
• 색상은 email-template.js 의 THEMES, 로고는 logos.js 한 곳에서 관리한다 (새 브랜드도 같은 방식으로 추가)

---

🧪 테스트

실제 네이버웍스·Upstash 에 붙지 않고, 가짜 저장소(메모리)와 가짜 메일 서버로 돈다. 비밀값도 필요 없다.

npm test          # 서버 테스트 (test/*.test.js) — 설치 없이 바로 돈다
npm run test:ui   # 화면 테스트 (test/ui/*.test.mjs) — playwright + chromium 필요

• 화면 테스트는 npm install --no-save playwright && npx playwright install chromium 뒤에 돌린다. Chromium 을 따로 깔아 뒀으면 CHROMIUM_PATH=<경로> 로 지정할 수 있다.
• GitHub 에 올리면 자동으로 둘 다 돈다 (.github/workflows/test.yml). 실패하면 GitHub 의 Actions 탭에 빨간 X 가 뜬다.
• 테스트 파일은 배포에서 빠진다 (.vercelignore).
• 기능을 고치면 해당 테스트도 같이 고치고, 새 기능엔 테스트를 더한다.

---

관련 프로젝트

매출·광고·회신 트래커 대시보드는 별도 레포(dalba-email)와 별도 Vercel 프로젝트에 있다. 헤더에 바로가기를 띄우려면 index.html 상단의 DASHBOARD_SITE 상수에 그 사이트 주소를 넣으면 된다.

아직 안 된 것

• 회신은 개수만 센다. "진행 중 / 성사 / 거절" 같은 상태는 아직 없다 — 자동 팔로업 시퀀스를 만들려면 그 상태 저장이 먼저 필요하다.
• 자동 동기화는 15분마다(Pro 플랜 크론) 돈다 — 회신·발송 기록이 그날 안에 계속 잡힌다. 급하면 버튼을 누르면 된다.
• 메일함 조회·가져오기는 실제 네이버웍스 IMAP 서버로는 검증하지 못했다 (개발 환경에서 접근 불가). 가짜 IMAP 서버로 권한·폴더탐색·회신대조·필터·중복방지 로직만 확인했다. 처음 켤 때 GET /api/mailbox?ping=1 로 연결부터 확인할 것.
• 화면은 3개 국어지만 메일 본문은 번역되지 않는다 — 담당자가 직접 쓰는 문구라서다.
• 열람·클릭 추적 없음