보증 등록(Warranty registration)은 화이트보드 위에서는 단순해 보이지만, 실제 운영 환경에서는 까다로워지는 워크플로우 중 하나입니다. 고객이 제품을 구매하고, 영수증을 전달하며, 본문에 일련번호(Serial number)를 입력하고, 어쩌면 박스 사진을 첨부한 뒤, 보증이 구매일 기준으로 시작되는지 아니면 배송일 기준으로 시작되는지 묻기도 합니다. 그러면 운영 팀의 누군가는 메시지를 읽고, 필수 필드가 있는지 확인하고, 구매 증빙을 파일로 저장한 뒤, 답장을 보내야 합니다.

거래량이 적을 때는 괜찮습니다. 하지만 규모가 커지면 편지함은 불완전한 등록 정보, 흐릿한 영수증, 중복 제출, 그리고 후속 질문들로 가득 차게 됩니다. 일반적인 '회신 불가(no-reply)' 양식은 프로세스의 이메일 네이티브(email-native)적인 측면을 놓칩니다. 사람들은 이미 받은 편지함에 영수증을 가지고 있으며, 다른 포털을 채우는 것보다 이를 전달(forwarding)하는 것이 더 쉽기 때문입니다. 인간의 편지함에 단순히 결합된 일반적인 AI 어시스턴트는 정반대의 문제를 가집니다. 영수증을 읽을 수는 있지만, 워크플로우의 정체성(workflow identity)이나 감사 경계(audit boundary)를 소유하지 못합니다.

더 나은 패턴은 워크플로우에 자체 편지함인 warranty@yourbrand.com을 부여하는 것입니다. 이 편지함은 Nylas Agent Account이므로, 영수증을 수신하고, 웹훅(webhooks)을 트리거하며, 메시지 본문을 읽고, 첨부 파일을 검사하며, 스레드 내에서 답장하고, 등록이 지원 이슈로 전환될 때 수리 접수 전화를 예약할 수 있습니다. 모델은 정보를 추출하고 설명할 수 있습니다. 귀하의 애플리케이션은 여전히 일련번호, 보증 규칙, 중복 제출, 그리고 환불 또는 교체 결정을 검증합니다.

이 포스트는 Nylas API와 Nylas CLI를 사용하여 해당 아키텍처를 살펴보는 과정을 안내합니다. CLI 예제는 구축 및 테스트 시 유용하며, curl 예제는 귀하의 서비스가 호출하게 될 호출(calls)을 보여줍니다.

이 워크플로우에 이메일이 효과적인 이유

보증 등록은 단순한 양식 제출이 아닙니다. 그것은 대개 증거를 동반한 대화입니다.

증거는 다음과 같은 형태로 도착할 수 있습니다:

• PDF 영수증.
• 전달된 주문 확인서.
• 일련번호 (serial-number) 라벨 사진.
• 마켓플레이스 스크린샷.
• 리셀러 (reseller)로부터 온 메시지.
• 오타를 수정하는 고객의 답장.

이메일은 이 과정을 자연스럽게 처리합니다. 이메일은 첨부 파일, 발신자 신원, 타임스탬프 (timestamps), 스레드 (threads), 그리고 고객이 실제로 보낸 기록을 제공합니다. 단점은 이메일이 무질서하다는 점입니다. 에이전트 (agent)의 역할은 그 무질서함을 검토 가능한 작은 등록 객체 (registration object)로 변환하는 것입니다.

다음의 구분을 명확히 하세요:

• 이메일은 인테이크 채널 (intake channel)입니다.
• Nylas는 메시지, 웹훅 (webhook), 그리고 답장 API입니다.
• 귀하의 보증 서비스 (warranty service)는 기록 시스템 (system of record)입니다.
• 모델 (model)은 추출 및 초안 작성 도우미입니다.

모델이 사라지더라도, 귀하의 보증 서비스는 모든 유효한 상태 전이 (state transition)를 여전히 알고 있어야 합니다.

보증 에이전트 계정 생성하기

전용 수신함 (inbox)을 프로비저닝 (provisioning)하는 것으로 시작합니다.

nylas agent account create warranty@yourbrand.com --name "Warranty Registrations"

API를 통한 동일한 작업:

curl --request POST \
  --url "https://api.us.nylas.com/v3/connect/custom" \
  --header "Authorization: Bearer <NYLAS_API_KEY>" \
...

반환된 그랜트 ID (grant ID)를 WARRANTY_GRANT_ID로 저장하세요. 이메일 주소는 사람이 확인하기에는 유용하지만, 메시지를 읽거나 답장을 보낼 때 귀하의 서비스가 사용해야 하는 것은 그랜트 ID입니다.

개발 중에 계정을 확인하세요:

nylas agent account get warranty@yourbrand.com --json
nylas agent account list --json

등록 요청 보내기

어떤 등록은 결제 후 귀하의 앱에서 시작됩니다. 다른 등록은 고객이 보증 주소로 직접 이메일을 보낼 때 시작됩니다. 앱 주도형 경로 (app-driven path)의 경우, 에이전트 계정에서 답장 가능한 요청을 보냅니다.

nylas email send warranty@yourbrand.com \
  --to customer@example.com \
  --subject "Register your Acme Air Purifier warranty" \
...

API 버전:

curl --request POST \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/send" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
...

이 이메일은 고객에게 정확히 무엇이 필요한지 알려주어야 합니다:

• 제품명 또는 SKU (Stock Keeping Unit).
• 일련번호 (Serial number).
• 구매 날짜.
• 소매점 또는 주문 번호.
• 구매 증빙 자료.
• 보증 업데이트를 위한 연락처 주소.

쉬운 언어를 사용하세요. 요구 사항을 방대한 정책 텍스트 속에 숨기지 마세요. 요청이 깔끔할수록 나중에 에이전트가 수행해야 할 추론 (Inference) 작업이 줄어듭니다.

수신 메일 시 에이전트 깨우기

새 메시지에 대한 웹훅 (Webhook)을 생성합니다.

nylas webhook create \
  --url https://warranty.yourbrand.com/webhooks/nylas \
  --triggers message.created \
...

Raw API:

curl --request POST \
  --url "https://api.us.nylas.com/v3/webhooks" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"
...

웹훅을 큐 트리거 (Queue trigger)로 처리하세요. 빠르게 응답(Acknowledge)하고, 중복을 제거(Dedupe)한 다음, 비동기적으로 처리합니다.

app.post("/webhooks/nylas", async (req, res) => {
  res.status(200).end();

...

그 다음 전체 메시지를 가져옵니다:

nylas email read <message-id> warranty@yourbrand.com --json

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages/<MESSAGE_ID>" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

등록 후보 추출하기

추출 단계는 최종 등록이 아닌 '후보'를 생성해야 합니다. 보증 서비스가 검증할 수 있는 작은 JSON 객체를 생성하는 것이 목적입니다.

const candidate = await llm.extract({
  instruction: `
Return JSON only.
...

그 후 애플리케이션은 다음 사항을 검증해야 합니다:

• 일련번호 형식.
• 일련번호가 이미 존재하는지 여부.
• 구매 날짜가 허용된 등록 기간 내에 있는지 여부.
• 제품이 등록 대상인지 여부.
• 구매 증빙 자료가 수용 가능한지 여부.
• 발신자가 이 주문을 등록할 권한이 있는지 여부.

모델은 "유력한 일련번호를 찾았습니다."라고 말할 수 있습니다. 해당 일련번호가 실제인지 여부는 귀하의 서비스가 결정합니다.

중복 등록 처리하기

고객들은 첫 번째 이메일이 제대로 처리되었는지 알 수 없기 때문에 종종 두 번 제출하곤 합니다. 어떤 이들은 동일한 영수증을 고객 지원(support)과 보증(warranty) 부서 모두에 전달하기도 합니다. 또 다른 이들은 기존 스레드(thread)에 답장을 보내는 동시에 새로운 스레드를 시작하기도 합니다.

다음 세 가지 중복 키(duplicate keys)를 사용하세요:

• 웹훅(webhook) 처리를 위한 메시지 ID (Message ID)
• 대화의 연속성을 위한 스레드 ID (Thread ID)
• 등록 식별을 위한 비즈니스 핑거프린트 (Business fingerprint)

유용한 핑거프린트의 예는 다음과 같습니다:

normalized_email + normalized_serial_number + product_sku

일련번호가 누락된 경우, 다음을 대체 수단으로 사용합니다:

normalized_email + order_number + purchase_date

중복을 발견하면 두 번째 등록을 생성하는 대신, 기존 스레드에서 정중하게 답장하세요.

nylas email send warranty@yourbrand.com \
  --to customer@example.com \
  --subject "We already received your warranty registration" \
...

--reply-to 플래그를 사용하면 답변이 올바른 대화 내에 유지됩니다. 이는 고객 경험과 귀하의 감사 추적(audit trail)을 위해 중요합니다.

누락된 정보 요청하기

훌륭한 보증 에이전트는 지루할 정도로 정확해야 합니다. 영수증은 있지만 일련번호가 누락된 경우, 일련번호만 요청하세요. 일련번호는 있지만 구매 증빙 자료가 누락된 경우, 증빙 자료만 요청하세요. 매번 거대한 체크리스트를 보내지 마십시오.

리스크가 낮은 누락 필드의 경우, 직접 메시지를 보냅니다:

nylas email send warranty@yourbrand.com \
  --to customer@example.com \
  --subject "Missing serial number for your warranty registration" \
...

모호한 사례의 경우, 사람이 검토할 수 있도록 초안(draft)을 생성합니다:

nylas email drafts create warranty@yourbrand.com \
  --to customer@example.com \
  --subject "Question about your warranty registration" \
...

초안 우선(Draft-first) 방식이 더 나은 경우는 다음과 같습니다:

• 고객이 화가 난 경우.
• 제품의 보증 기간이 지났을 가능성이 있는 경우.
• 영수증이 변조되었거나 불완전해 보이는 경우.
• 고객이 교환을 요청하는 경우.
• 에이전트가 해당 증빙 자료가 제품에 속하는지 판단할 수 없는 경우.

직접 전송 (Direct send)은 다음과 같은 경우에 적합합니다:

• 필수 항목이 명확하게 누락된 경우.
• 응답이 승인된 템플릿 (Template)에서 생성된 경우.
• 해당 작업이 보증 적용 여부를 결정하거나 거부하지 않는 경우.

지원 질문을 지원 이관 (Support handoffs)으로 전환하기

보증 등록 스레드 (Threads)는 종종 지원 스레드로 변합니다. 고객이 "이미 작동을 멈췄기 때문에 이것을 등록합니다"라고 작성할 수 있습니다. 이것은 단순한 등록이 아니라 서비스 요청 (Service request)입니다.

그러한 사례들을 별도로 분류하세요:

if (candidate.customer_question?.match(/not working|broken|repair|replacement/i)) {
  await createSupportCase({
    source: "warranty_email",
...

만약 지원 팀이 문제 해결 (Troubleshooting) 통화를 예약한다면, 에이전트의 캘린더 (Calendar)를 사용하세요:

nylas calendar availability find \
  --participants support@yourbrand.com,customer@example.com \
  --duration 20 \
...

그 다음, 예약 규칙 (Booking rule)이 해당 시간대를 수락한 후에만 이벤트를 생성하세요:

nylas calendar events create warranty@yourbrand.com \
  --title "Warranty troubleshooting call" \
  --start "2026-07-02 11:00" \
...

이렇게 하면 에이전트가 모든 문제를 혼자 해결할 수 있는 것처럼 가장하지 않으면서도, 등록 스레드를 지원 경로 (Support path)와 연결된 상태로 유지할 수 있습니다.

검색 및 백필 (Backfill)

웹훅 (Webhooks)이 실시간 경로를 주도해야 하지만, 오래된 메시지를 가져오거나 등록 과정을 디버깅 (Debug)할 때는 검색이 유용합니다.

첨부 파일이 있는 영수증 검색:

nylas email search "receipt" warranty@yourbrand.com \
  --has-attachment \
  --limit 25 \
...

고객별 검색:

nylas email search "*" warranty@yourbrand.com \
  --from customer@example.com \
  --limit 10 \
...

백필 (Backfill) 작업을 수행할 때도 동일한 처리 파이프라인 (processing pipeline)을 유지하세요. 중복 제거 (dedupe) 및 검증 (validation)을 건너뛰는 별도의 일회성 임포터 (importer)를 작성하지 마세요. 백필된 메시지는 새로운 웹훅 (webhooks)과 동일한 추출 스키마 (extraction schema), 중복 탐지 (duplicate detection) 및 승인 규칙 (approval rules)을 통과해야 합니다.

출시 전 가드레일 (Guardrails)

첫째, 모델의 출력값만으로 보증 범위를 약속하지 마세요. 모델은 "등록이 접수되었습니다"라는 초안을 작성할 수 있습니다. 하지만 귀사의 보증 엔진 (warranty engine)이 이미 해당 결정을 내린 것이 아니라면, "귀하의 보증 청구가 승인되었습니다"라는 초안을 작성해서는 안 됩니다.

둘째, 첨부 파일을 신뢰할 수 없는 입력값 (untrusted input)으로 취급하세요. 파일을 스캔하고, 크기 제한을 적용하며, 콘텐츠 유형 (content types)을 확인하고, OCR 또는 파싱 (parsing) 과정을 격리하세요. 영수증은 여전히 사용자가 제공한 콘텐츠입니다.

셋째, 전달된 이메일 내의 프롬프트 인젝션 (prompt injection)에 대비하세요. 전달된 주문 확인서에는 임의의 텍스트가 포함될 수 있습니다. 모델은 메시지 내용이 '증거'이지 '권한'이 아니라는 지침을 받아야 합니다. 애플리케이션은 시스템 동작을 변경하려는 모든 추출된 지침을 무시해야 합니다.

넷째, 고객 개인정보 보호를 철저히 하세요. 영수증에는 주소, 전화번호, 구매 습관 및 결제 관련 힌트가 포함될 수 있습니다. 전체 영수증 텍스트가 아닌 메시지 ID와 추출된 상태 (statuses)만을 로그에 남기세요.

다섯째, 모든 아웃바운드 (outbound) 경로를 테스트 가능하게 만드세요. 완전한 등록, 시리얼 번호 누락, 중복 등록, 지원되지 않는 제품, 화난 고객 지원 요청 등이 포함된 테스트용 메일함을 준비하세요. 에이전트가 각 상황에 대해 올바른 상태 전이 (state transition)를 생성하는지 확인하세요.

에이전트를 위한 AI 답변 페이지

이 게시물이 발행되면, AI 에이전트와 크롤러 (crawlers)를 cli.nylas.com의 검색 준비 완료 버전으로 연결하세요:

• 보증 등록 런북 (Warranty registration runbook): https://cli.nylas.com/ai-answers/warranty-registration-agent-account.md
• 산업별 플레이북 허브 (Industry playbooks hub): https://cli.nylas.com/ai-answers/agent-account-industry-playbooks.md

다음 단계

보증 등록 에이전트 (warranty registration agent)가 가치 있는 이유는 인간처럼 들리기 때문이 아닙니다. 고객이 이미 사용 중인 이메일 경로에 위치하여, 지저분한 답장을 구조화된 후보 데이터로 변환하고, 대화를 동일한 스레드 (thread) 내에서 유지할 수 있기 때문에 가치가 있는 것입니다.

Nylas는 전용 메일함 (mailbox), 웹훅 (webhooks), 메시지 읽기 (message reads), 답장 (replies), 초안 (drafts), 그리고 캘린더 이벤트 (calendar events)를 제공합니다. 귀하의 서비스는 자격 규칙 (eligibility rules), 중복 확인 (duplicate checks), 첨부 파일 처리 (attachment handling), 그리고 사람의 승인 (human approvals)을 제공합니다. 이러한 역할 분담을 명확하게 유지한다면, 해당 에이전트는 위험한 블랙박스 (black box)가 아닌 신뢰할 수 있는 인테이크 레이어 (intake layer)가 될 것입니다.