이메일로 로그인·인증 구현하기

bldinit Email 앱은 트랜잭션 이메일 발송을 담당합니다 — 가입 인증, 매직링크 로그인, OTP, 영수증, 알림. 토큰·검증 로직은 당신의 앱에서, 발송·DKIM·도달·바운스/신고 suppression·PII 마스킹은 bldinit 이 처리합니다. AI 에이전트(MCP)로도, 코드(REST)로도 동일.

사전 준비 (2가지)

1. 발송 도메인 인증 — 대시보드 Domains 에서 도메인 등록 → 안내된 CNAME 3개(DKIM) 를 DNS 에 추가 → verified. 인증된 도메인에서만 발송됩니다.
2. API 키 발급 — API keys 에서 키 생성 시 스코프 email:send 선택(발송 전용 — 유출돼도 발송만 가능). mw_... 값을 복사합니다.

보내기 — REST

curl https://app.bldinit.com/api/v1/email/send \
  -H "X-API-Key: mw_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from_email": "noreply@yourdomain.com",
    "to": "user@example.com",
    "subject": "이메일을 인증해 주세요",
    "html": "<p>아래 링크로 인증하세요: <a href=\"https://yourapp.com/verify?token=abc\">인증하기</a></p>"
  }'

요청 필드: from_email(인증된 도메인), to, subject, html(또는 template_id+variables), 선택 text · reply_to · cc · bcc · idempotency_key · scheduled_at(ISO-8601 미래 시각). 응답에 message_id 가 옵니다. 바운스·신고는 자동으로 suppression 처리됩니다.

// Node (fetch)
await fetch("https://app.bldinit.com/api/v1/email/send", {
  method: "POST",
  headers: { "X-API-Key": process.env.BLDINIT_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    from_email: "noreply@yourdomain.com",
    to: email,
    subject: "이메일을 인증해 주세요",
    html: `<p><a href="https://yourapp.com/verify?token=${token}">인증하기</a></p>`,
    idempotency_key: `verify:${userId}`,
  }),
});

보내기 — AI 에이전트 (MCP)

Claude·Cursor 등을 bldinit MCP 에 연결하면 AI 가 직접 발송합니다. 설정에 한 줄:

{ "mcpServers": { "bldinit": { "url": "https://app.bldinit.com/gateway/mcp" } } }

그다음 자연어로 — “noreply@yourdomain.com 에서 user@example.com 로 인증 링크 메일 보내줘” → AI 가 send_email 도구를 호출합니다. 도구: send_email · send_email_batch · create_email_template.

---

레시피

공통 원칙: bldinit 은 메일을 보낼 뿐, 토큰 생성·저장·검증은 당신의 앱이 합니다. 토큰은 추측 불가능하게(CSPRNG), 만료를 두고(예: 링크 30분, OTP 5분), 1회용으로 처리하세요.

1) 이메일 인증 (가입)

1. 가입 시 토큰 생성 → DB 저장(user_id, token, expires_at)
2. bldinit 으로 인증 링크 메일 발송 (아래)
3. 사용자가 링크 클릭 → /verify?token= → 토큰 확인 → 계정 활성화

curl https://app.bldinit.com/api/v1/email/send -H "X-API-Key: mw_..." \
  -H "Content-Type: application/json" -d '{
  "from_email":"noreply@yourdomain.com","to":"user@example.com",
  "subject":"이메일을 인증해 주세요",
  "html":"<p>가입을 완료하려면 인증해 주세요:</p><p><a href=\"https://yourapp.com/verify?token=TOKEN\">이메일 인증</a></p><p>이 링크는 30분 후 만료됩니다.</p>"
}'

2) 매직링크 로그인 (비밀번호 없는 로그인)

1. 로그인 요청(이메일 입력) → 일회용 토큰 생성·저장(짧은 만료)
2. 매직링크 메일 발송
3. 링크 클릭 → 토큰 검증 → 세션 발급 → 토큰 폐기

{
  "from_email": "login@yourdomain.com",
  "to": "user@example.com",
  "subject": "로그인 링크",
  "html": "<p>아래 버튼으로 로그인하세요(15분 유효):</p><p><a href=\"https://yourapp.com/auth/magic?token=TOKEN\" style=\"display:inline-block;padding:10px 18px;background:#4f46e5;color:#fff;border-radius:8px;text-decoration:none\">로그인</a></p><p>본인이 요청하지 않았다면 이 메일을 무시하세요.</p>"
}

3) OTP (일회용 코드)

1. 6자리 코드 생성 → 해시해서 저장(코드 원문 저장 X), 5분 만료
2. 코드 메일 발송
3. 사용자가 입력 → 해시 비교 → 통과 시 코드 폐기

{
  "from_email": "noreply@yourdomain.com",
  "to": "user@example.com",
  "subject": "인증 코드: 482913",
  "html": "<p>인증 코드입니다:</p><p style=\"font-size:28px;font-weight:700;letter-spacing:4px;font-family:monospace\">482913</p><p>5분 안에 입력하세요. 본인이 요청하지 않았다면 무시하세요.</p>"
}

4) 환영 메일 (가입 완료 후)

{
  "from_email": "team@yourdomain.com",
  "to": "user@example.com",
  "subject": "가입을 환영합니다 🎉",
  "html": "<p>{{name}}님, 가입을 환영합니다!</p><p>시작하기: <a href=\"https://yourapp.com/start\">대시보드 열기</a></p>",
  "template_id": "welcome",
  "variables": { "name": "홍길동" }
}

5) 비밀번호 재설정

{
  "from_email": "noreply@yourdomain.com",
  "to": "user@example.com",
  "subject": "비밀번호 재설정",
  "html": "<p>아래 링크로 비밀번호를 재설정하세요(1시간 유효):</p><p><a href=\"https://yourapp.com/reset?token=TOKEN\">비밀번호 재설정</a></p><p>본인이 요청하지 않았다면 무시하세요 — 비밀번호는 변경되지 않습니다.</p>"
}

---

템플릿 재사용

매번 HTML 을 보내는 대신 템플릿을 저장하고 변수로 채웁니다:

# 1) 템플릿 저장 (대시보드 Templates 또는 MCP create_email_template)
#    본문에 {{변수}} 사용 — 값은 발송 시 자동 escape
# 2) 발송 시 template_id + variables
curl https://app.bldinit.com/api/v1/email/send -H "X-API-Key: mw_..." \
  -H "Content-Type: application/json" -d '{
  "from_email":"noreply@yourdomain.com","to":"user@example.com",
  "template_id":"verify","variables":{"link":"https://yourapp.com/verify?token=abc"}
}'

⚠️ 인증 코드·링크 같은 1회성 민감정보는 발송 본문에만 넣고 저장 템플릿에는 넣지 마세요 (템플릿은 저장됩니다). 변수로 주입하세요.

도달·운영

• 바운스/신고 자동 처리 — 하드바운스·신고는 자동으로 suppression 목록에 올라가고, 이후 그 주소로는 발송이 차단됩니다(평판 보호).
• 재시도 안전 — 같은 idempotency_key 로 재요청하면 중복 발송되지 않습니다.
• PII — 수신자 주소는 해시로 기록되고 원문은 저장하지 않습니다. 로그/템플릿에 개인정보를 넣지 마세요.
• 무료 티어 로 시작, 발송량이 늘면 앱 안에서 구독/탑업.

대시보드: Email → Developers 에서 내 계정 기준 예제와 키 발급 링크를 볼 수 있습니다.