Claude Code로 SendGrid 이메일을 안전하게 구현하는 방법

SendGrid는 애플리케이션에서 API로 이메일을 보내기 위한 클라우드 이메일 전송 서비스입니다. 문의 폼 확인 메일, 회원가입 후 온보딩 메일, 일일 리포트, 거래성 알림, 그리고 명확한 수신 거부 절차가 있는 영업 후속 메일에 사용할 수 있습니다.

문제는 이메일 코드가 짧아 보인다는 점입니다. Claude Code에 “SendGrid로 이메일 보내는 기능을 만들어줘”라고만 요청하면 API 호출 코드는 나오지만, 검증된 발신자, API 키 보관, 재시도 중복 발송, bounce, spam complaint, provider log, opt-out 처리가 빠질 수 있습니다. 메일은 한번 나가면 되돌릴 수 없으므로, 초보자일수록 코드보다 먼저 운영 경계를 정해야 합니다.

이 글은 Twilio SendGrid 공식v3 Mail Send API, SendGrid의Validation Error 문서, 그리고SendGrid 제품 페이지를 기준으로 합니다. 복사해서 실행할 수 있는 Node.js 스크립트도 포함합니다. 기본은 dry-run이라 실제 발송하지 않으며, --send를 붙였을 때만 SendGrid를 호출합니다. payload 검증, sandbox 검증, 임시 오류 재시도, 로컬 발송 로그, 간단한 idempotency guard도 들어 있습니다.

기초를 함께 정리하려면 Claude Code 이메일 자동화, API 개발, 환경 변수 관리, 보안 베스트 프랙티스를 이어서 보면 좋습니다.

구현 전에 알아야 할 SendGrid 기본

SendGrid Mail Send는 POST https://api.sendgrid.com/v3/mail/send로 JSON을 보내고, 헤더에Authorization: Bearer SENDGRID_API_KEY를 넣는 API입니다. 호출 자체는 단순하지만, 운영에서는 아래 항목을 먼저 확인해야 합니다.

항목	쉬운 설명	확인할 것
Verified Sender	SendGrid가 이 from 주소로 보내도 된다고 확인한 발신자	작은 테스트는 Single Sender, 운영은 Domain Authentication 사용
Domain Authentication	DNS로 내 도메인이 SendGrid를 통해 보낼 수 있음을 증명	SPF/DKIM 레코드가 검증된 뒤 운영 발송
API Key	서버가 SendGrid API를 호출할 때 쓰는 비밀 키	서버 환경 변수에만 두고, 노출 시 즉시 교체
personalizations	수신자별 주소, 제목, custom args, template data를 담는 배열	한 personalization에는 한 명만 넣어 수신자 목록 노출 방지
suppression	bounce, complaint, unsubscribe 때문에 보내면 안 되는 주소	SendGrid 호출 전에 자체 suppression table 확인
provider log	SendGrid의 HTTP 상태, 응답 본문, x-message-id	장애 분석, 고객 문의, 중복 발송 방지에 사용

SPF는 어떤 서버가 도메인을 대신해 메일을 보낼 수 있는지 알려주는 DNS 레코드입니다. DKIM은 메일이 승인되었고 중간에 바뀌지 않았음을 검증하는 서명입니다. DMARC는 SPF나 DKIM 정렬이 실패했을 때 수신 서버가 참고하는 정책입니다. 처음부터 모든 용어를 외울 필요는 없지만, 발신자 인증이 도달률의 신분증이라는 점은 이해해야 합니다.

from에 임의의 Gmail 주소를 넣고 시작하지 마세요. 로컬 검증은 SendGrid Single Sender로 충분하지만, 운영에서는 자체 도메인 인증을 완료한 뒤 제품 또는 지원 주소로 보내는 편이 안전합니다. 많은 Validation Error는 잘못된 from, 비어 있거나 틀린personalizations, content 누락, template 설정 오류에서 시작됩니다.

네 가지 실전 사용 사례

모든 메일을 하나의 sendMail 함수로 묶으면 운영이 어려워집니다. 목적마다 동의, 빈도, 실패 영향, 로그 수준이 다릅니다.

사용 사례	예	필요한 안전장치
문의 폼 메일	방문자에게 접수 확인, 팀에게 알림	사용자 입력을 HTML에 직접 넣지 말고, 관리자용과 사용자용을 분리
트랜잭션 온보딩	가입 완료, 첫 로그인 안내, 구매 후 가이드	사용자가 기대한 내용에 집중하고 과한 홍보를 섞지 않기
일일 리포트	매출, 오류 요약, 예약, 학습 진척	재시도해도 중복처럼 보이지 않도록 idempotency key 사용
영업 또는 아웃리치	미팅 후 자료, 제안서 follow-up, 휴면 고객 안내	opt-out, 발송 이유, 회사 정보, suppression 확인

특히 아웃리치는 기술과 법무가 분리되어야 합니다. 보낼 수 있다는 것과 보내도 된다는 것은 다릅니다. 국가, 기존 관계, B2B/B2C 여부, 수신자가 기대한 맥락에 따라 판단이 달라집니다. 이 글은 구현 가이드이지 법률 자문이 아닙니다. 최소한 수신 거부 경로를 제공하고, 거부한 주소에는 다시 보내지 않는 구조가 필요합니다.

flowchart LR
  App["앱 / Claude Code 변경"]
  Validate["payload 검증"]
  Log["발송 로그와 idempotency key"]
  SendGrid["SendGrid Mail Send API"]
  Inbox["수신함"]
  Events["Bounce / Spam / Unsubscribe"]
  Suppression["Suppression list"]

  App --> Validate --> Log --> SendGrid --> Inbox
  SendGrid --> Events --> Suppression
  Suppression --> Validate

복사해서 실행하는 Node.js 스크립트

아래 스크립트는 Node.js 20 이상에서 동작하며 별도 패키지가 필요 없습니다. 기본 실행은 dry-run이라 payload를 출력하고 로그만 남기며 SendGrid를 호출하지 않습니다. 실제 API 호출은--send, 검증만 하고 배달하지 않으려면--send --sandbox를 사용합니다.

// sendgrid-safe-send.mjs
import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
import { readFile, writeFile } from "node:fs/promises";

const ENDPOINT = process.env.SENDGRID_API_BASE ?? "https://api.sendgrid.com/v3/mail/send";
const LOG_PATH = process.env.SENDGRID_SEND_LOG ?? ".sendgrid-send-log.json";
const DRY_RUN = !process.argv.includes("--send");
const SANDBOX = process.argv.includes("--sandbox");
const MAX_ATTEMPTS = Number.parseInt(process.env.SENDGRID_MAX_ATTEMPTS ?? "3", 10);

const recipient = {
  email: process.env.MAIL_TO ?? "recipient@example.com",
  name: process.env.MAIL_TO_NAME ?? "Test Recipient",
};

const message = {
  from: {
    email: process.env.MAIL_FROM ?? "verified-sender@example.com",
    name: process.env.MAIL_FROM_NAME ?? "ClaudeCodeLab Demo",
  },
  reply_to: {
    email: process.env.MAIL_REPLY_TO ?? process.env.MAIL_FROM ?? "verified-sender@example.com",
  },
  personalizations: [
    {
      to: [recipient],
      custom_args: {
        use_case: process.env.MAIL_USE_CASE ?? "dry_run_demo",
      },
    },
  ],
  subject: process.env.MAIL_SUBJECT ?? `SendGrid dry-run test for ${recipient.name}`,
  content: [
    {
      type: "text/plain",
      value: `Hello ${recipient.name},\n\nThis is a safe SendGrid test from Claude Code.\n`,
    },
    {
      type: "text/html",
      value: `<p>Hello ${escapeHtml(recipient.name)},</p><p>This is a safe SendGrid test from Claude Code.</p>`,
    },
  ],
  categories: ["claude-code-demo"],
  mail_settings: {
    sandbox_mode: { enable: SANDBOX },
  },
};

validatePayload(message);
const idempotencyKey = makeIdempotencyKey(message);
for (const personalization of message.personalizations) {
  personalization.custom_args = {
    ...(personalization.custom_args ?? {}),
    idempotency_key: idempotencyKey,
  };
}

await sendWithRetry(message, idempotencyKey);

function validatePayload(payload) {
  if (!Number.isInteger(MAX_ATTEMPTS) || MAX_ATTEMPTS < 1 || MAX_ATTEMPTS > 5) {
    throw new Error("SENDGRID_MAX_ATTEMPTS must be an integer from 1 to 5.");
  }

  assertEmail(payload.from?.email, "from.email");
  if (!DRY_RUN && payload.from.email.endsWith("@example.com")) {
    throw new Error("Set MAIL_FROM to a verified SendGrid sender before using --send.");
  }

  if (!Array.isArray(payload.personalizations) || payload.personalizations.length === 0) {
    throw new Error("personalizations must contain at least one recipient.");
  }

  for (const [index, personalization] of payload.personalizations.entries()) {
    if (!Array.isArray(personalization.to) || personalization.to.length !== 1) {
      throw new Error(`personalizations[${index}].to must contain exactly one recipient.`);
    }
    assertEmail(personalization.to[0]?.email, `personalizations[${index}].to[0].email`);
  }

  if (!payload.subject && !payload.template_id) {
    throw new Error("Provide a subject or a SendGrid template_id.");
  }

  const hasContent = Array.isArray(payload.content)
    && payload.content.some((item) => typeof item.value === "string" && item.value.trim());
  if (!hasContent && !payload.template_id) {
    throw new Error("Provide text/html content or a SendGrid template_id.");
  }
}

function assertEmail(value, field) {
  if (typeof value !== "string" || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)) {
    throw new Error(`${field} must be a valid email address.`);
  }
}

function makeIdempotencyKey(payload) {
  const stableEnvelope = {
    from: payload.from.email.toLowerCase(),
    to: payload.personalizations.map((item) => item.to[0].email.toLowerCase()),
    subject: payload.subject,
    content: payload.content?.map((item) => item.value),
    useCase: payload.personalizations.map((item) => item.custom_args?.use_case ?? ""),
  };
  return createHash("sha256").update(JSON.stringify(stableEnvelope)).digest("hex").slice(0, 32);
}

async function sendWithRetry(payload, idempotencyKey) {
  const log = await readJsonLog();
  const previous = log[idempotencyKey];

  if (previous?.status === "accepted") {
    console.log(`Already accepted by SendGrid. idempotencyKey=${idempotencyKey}`);
    return;
  }
  if (previous?.status === "pending") {
    throw new Error(`A send is already pending. idempotencyKey=${idempotencyKey}`);
  }

  if (DRY_RUN) {
    log[idempotencyKey] = {
      status: "dry-run",
      updatedAt: new Date().toISOString(),
      to: payload.personalizations.map((item) => item.to[0].email),
    };
    await writeJsonLog(log);
    console.log("Dry run only. Add --send to call SendGrid.");
    console.log(JSON.stringify({ idempotencyKey, payload }, null, 2));
    return;
  }

  const apiKey = process.env.SENDGRID_API_KEY;
  if (!apiKey) {
    throw new Error("SENDGRID_API_KEY is required when using --send.");
  }

  log[idempotencyKey] = { status: "pending", updatedAt: new Date().toISOString() };
  await writeJsonLog(log);

  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
    const response = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });
    const responseBody = await response.text();
    const providerMessageId = response.headers.get("x-message-id");

    if (response.status === 202) {
      log[idempotencyKey] = {
        status: "accepted",
        statusCode: response.status,
        providerMessageId,
        updatedAt: new Date().toISOString(),
      };
      await writeJsonLog(log);
      console.log(`Accepted by SendGrid. idempotencyKey=${idempotencyKey}`);
      return;
    }

    const retryable = response.status === 429 || response.status >= 500;
    log[idempotencyKey] = {
      status: retryable && attempt < MAX_ATTEMPTS ? "retrying" : "failed",
      statusCode: response.status,
      responseBody: responseBody.slice(0, 2000),
      attempt,
      updatedAt: new Date().toISOString(),
    };
    await writeJsonLog(log);

    if (!retryable || attempt === MAX_ATTEMPTS) {
      throw new Error(`SendGrid request failed with HTTP ${response.status}: ${responseBody}`);
    }

    await sleep(Math.min(1000 * 2 ** (attempt - 1), 8000));
  }
}

async function readJsonLog() {
  if (!existsSync(LOG_PATH)) return {};
  return JSON.parse(await readFile(LOG_PATH, "utf8"));
}

async function writeJsonLog(log) {
  await writeFile(LOG_PATH, `${JSON.stringify(log, null, 2)}\n`, "utf8");
}

function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

function escapeHtml(value) {
  return String(value)
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#39;");
}

먼저 dry-run을 실행합니다. Windows PowerShell에서는 다음처럼 실행합니다.

node .\sendgrid-safe-send.mjs

$env:SENDGRID_API_KEY="SG.xxxxx"
$env:MAIL_FROM="verified@example.com"
$env:MAIL_TO="you@example.net"
node .\sendgrid-safe-send.mjs --send --sandbox

node .\sendgrid-safe-send.mjs --send

macOS나 Linux에서는 다음 형태를 사용할 수 있습니다.

SENDGRID_API_KEY="SG.xxxxx" MAIL_FROM="verified@example.com" MAIL_TO="you@example.net" node sendgrid-safe-send.mjs --send --sandbox

로컬 JSON 로그는 튜토리얼용입니다. 운영에서는 Postgres, Redis, SQS, Cloud Tasks 같은 내구성 있는 큐로 바꾸고, idempotency_key에 unique constraint를 두세요. SendGrid가 요청을 받았다는 사실과 비즈니스적으로 다시 보내도 된다는 판단은 별개입니다.

Claude Code에 줄 프롬프트

아래처럼 업무 목표와 실패 조건을 함께 전달하면, Claude Code가 단순 API 호출보다 넓은 설계를 하게 됩니다.

이 저장소에 SendGrid 이메일 전송을 추가해 주세요.
대상 워크플로는 문의 폼 확인, 회원가입 온보딩, 일일 리포트, 영업 follow-up입니다.

제약:
- SendGrid Mail Send API v3를 사용합니다.
- API 키는 서버 측 환경 변수 SENDGRID_API_KEY에서만 읽습니다.
- 모든 스크립트는 기본 dry-run이고, --send가 있을 때만 실제 전송합니다.
- 수신자 목록 노출을 막기 위해 personalization 하나에 수신자 한 명만 둡니다.
- 429와 5xx만 exponential backoff로 재시도합니다.
- 발송 전 unsubscribe, bounce, spam complaint suppression을 확인합니다.
- provider response, HTTP status, x-message-id, idempotency key를 저장합니다.
- outreach 메일에는 opt-out 경로를 넣습니다.
- README에 공식 SendGrid 문서 링크를 남깁니다.

먼저 설계표와 수정 예정 파일 목록만 보여 주세요. 승인 후 편집하세요.

이 프롬프트는 동의, suppression, 로그, 재시도, 파일 범위를 강제합니다. 병렬 작업 중에도 먼저 파일 목록을 확인할 수 있어 충돌을 줄이는 데 도움이 됩니다.

자주 발생하는 실패

실패	결과	예방
API 키 유출	다른 사람이 계정으로 대량 발송해 평판과 계정 상태를 망칠 수 있음	.env ignore, secret scanning, 즉시 키 rotation
미검증 sender	validation error, 차단, 낮은 inbox placement	Single Sender 또는 Domain Authentication 완료
재시도 중복 발송	같은 영수증, 보고서, follow-up이 여러 번 도착	provider 호출 전 send log와 idempotency key 확인
opt-out 없는 outreach	complaint와 법적 리스크 증가	수신 거부, 회사 정보, 발송 이유 명시
너무 빠른 발송	rate limit과 도메인 평판 하락	소량부터 ramp up하고 bounce와 complaint 비율 관찰
provider response 미저장	장애 때 무엇이 일어났는지 설명 불가	status, response body, x-message-id, 수신자 hash 저장
수신자 목록 노출	다른 사용자의 이메일 주소가 보임	personalization 하나에 수신자 한 명 원칙 유지

SendGrid의202 Accepted는 받은 편지함 도착을 의미하지 않습니다. SendGrid가 요청을 처리하기 위해 받았다는 뜻입니다. 이후 bounce, block, spam report, unsubscribe 이벤트를 봐야 실제 운영 판단을 할 수 있습니다.

도달률과 CTA 설계

도달률은 DNS만으로 결정되지 않습니다. 발신자 인증, 수신자의 기대, 발송 빈도, bounce 기록, complaint 비율, 문장의 명확성이 모두 영향을 줍니다. 운영에서는 전송 수, accepted, bounce, blocked, spam report, unsubscribe를 최소 지표로 봐야 합니다.

ClaudeCodeLab식 퍼널에 연결할 때는 CTA도 문맥에 맞춰야 합니다. 문의 확인 메일은 관련 글을, 온보딩 메일은 체크리스트나 템플릿을, 일일 리포트는 운영 정보 중심으로 둡니다. 팀 단위로 실제 저장소에 적용해야 한다면 Claude Code 교육 및 컨설팅에서 SendGrid 설정, 환경 변수, 보안 점검, suppression 설계, 로그 설계를 함께 정리할 수 있습니다.

실제 검증 결과

Masa가 이 샘플을 로컬에서 확인했을 때 가장 효과적인 안전장치는 dry-run을 기본값으로 둔 점이었습니다. 옵션 없이 실행하면 payload와 로컬 로그만 남고, MAIL_FROM이@example.com인 상태에서--send를 붙이면 API 호출 전에 멈춥니다. --send --sandbox는 실제 배달 없이 요청 구조를 검증하는 데 유용했습니다. 실무에서는 이 로컬 로그를 unique constraint가 있는 데이터베이스 큐로 바꾸고, bounce, spam complaint, unsubscribe 이벤트를 발송 전 suppression 체크로 되돌리는 구조가 안전합니다.