Gmail 수신 자동화 검수: 변경 알림과 신규 메일을 구분하는 법
Gmail 수신 자동화에서 변경 알림을 신규 메일로 잘못 세지 않는 검수 기준입니다. 메시지 식별자·변경 유형·최초 연결·재동기화 표본으로 업무 후보의 중복과 누락을 점검합니다.
이 글을 쓴 알파카랩스카카오·네이버·쿠팡 출신, 재하청 0%, 대기업·공공기관 등 18개사+ 레퍼런스
Gmail 수신 자동화는 알림 뒤 변경 유형과 실제 메일을 확인합니다. 2026-10-26 기준, 알림 수가 신규 수신 건수는 아닙니다.
메일을 읽었을 뿐인데 새 업무가 생기거나, 연동을 처음 켜자 과거 메일이 신규 요청으로 등록될 수 있습니다. AI의 요청 추출을 검수하기 전에 어떤 메시지를 신규 수신 후보로 보냈는지부터 확인해야 합니다.
Gmail 연동을 선택한 경우의 설계 예시입니다. 다른 메일 공급자의 이벤트·조회 계약은 별도로 확인합니다. 후보에서 요청별 상태를 확정하는 방법은 영업 메일 후속 업무 관리에서 이어 보고, 여기서는 변경 통지와 수신 후보 판정을 다룹니다.
Gmail 변경 알림을 신규 메일 한 통으로 세면 왜 틀리나요?#
알림은 메일함의 변경을 확인하라는 신호입니다. 메일 본문이나 새 업무의 개수를 뜻하지 않습니다. 변경 내역과 실제 메시지를 읽어 합의한 수신 범위에 들어오는지 판정해야 합니다.
Google의 Gmail push 공식 문서는 알림에 메일함 주소와 historyId를 전달한다고 설명합니다. Pub/Sub의 messageId는 Gmail 메시지와 무관한 식별자이며, watch 성공 직후에도 초기 알림이 전송됩니다. 문서 갱신일은 2026년 9월 15일 UTC, 확인일은 2026년 10월 26일입니다.
| 식별 단위 | 무엇을 식별하나요? | 업무에서 혼동하지 않을 것 |
|---|---|---|
| Pub/Sub messageId | 전달받은 알림 메시지 | Gmail 원문이나 요청의 고유 키로 쓰지 않음 |
| Gmail historyId | 메일함 변경 기록의 위치 | 증가량을 새 메일 수로 계산하지 않음 |
| Gmail 메시지 식별자 | 해당 메일함의 실제 메일 | 계정과 함께 대조하고 재처리를 새 수신으로 세지 않음 |
| 업무 요청 식별자 | 사람이 확인할 요청·산출물 단위 | 메일 한 통에 요청이 없거나 여러 개일 수 있음 |
표는 식별 책임을 나누는 제안입니다. 알림을 저장한 사실, 대상 메일을 확인한 사실, 업무를 확정한 사실은 각각 남깁니다. 알림 수신 성공만으로 원문 수집이나 업무 등록이 끝났다고 표시하지 않습니다.
변경 내역에서 어떤 메시지를 신규 수신 후보로 고르나요?#
추가·삭제·라벨 변경을 구분한 뒤 실제 메시지와 수신 정책을 대조합니다. 메일함에 추가됐다는 사실만으로 고객이 보낸 새 요청을 확정할 수는 없습니다. 발신·임시저장·가져오기와 과거 메일을 구별해야 합니다.
Gmail history.list 공식 명세는 messagesAdded, messagesDeleted, labelsAdded, labelsRemoved를 제공합니다. 일반 messages 필드는 구체 변경 유형 필드와 같은 메시지를 중복 포함할 수 있어 구체 필드 사용을 권고합니다. historyId도 연속 번호가 아니므로 차이를 건수로 해석하지 않습니다. 명세 갱신일은 2026년 4월 15일 UTC이며 2026년 10월 26일 확인했습니다.
업무 정책에는 허용 메일함·대상 자료·시작 기준선·과거 이관 여부를 적습니다. 수신 근거와 원문이 충분하지 않으면 후보를 보류합니다. 같은 메일의 읽음 표시가 바뀌었다고 사람이 확정한 요청의 담당자·기한·완료 상태를 자동으로 덮어쓰지 않습니다.
특정 라벨에 들어올 때 업무를 시작하는 설계도 가능합니다. 이 경우에는 신규 수신과 라벨 진입을 별도 시작 조건으로 정하고, 기존 메일이 다시 들어왔을 때 재개할지 새 후보를 만들지 검수합니다. 고객·기회와의 연결은 이메일·캘린더 CRM 연동 기준으로 별도 확인할 수 있습니다.
읽음·라벨·초기 연결을 어떤 표본으로 검수하나요?#
신규 수신이 아닌 변경을 섞어도 새 후보를 늘리지 않는지 확인합니다. 반대로 알림 한 번으로 조회한 범위에 여러 대상 메시지가 있으면 모두 확인해야 합니다. 알림 개수에 맞춰 후보 개수를 정하지 않습니다.
각 행은 독립 가상 표본입니다. 정책은 ‘허용 메일함에서 시작 기준선 이후 처음 수신한 대상 메일만 새 후속 후보’로 같습니다. M·N은 이 조건을 충족하는 서로 다른 수신 메일이며, 후보는 업무 확정 전 단계입니다.
| 독립 가상 표본 | 조회로 확인한 사실 | 같은 정책의 기대 결과 |
|---|---|---|
| 알림 뒤 M·N 확인 | 변경 범위를 조회해 신규 수신 M·N을 확인 | 두 메일을 각각 후보 검토. 업무 두 건으로 확정하지 않음 |
| 같은 M을 재처리 | 같은 메일함·메시지이며 이미 후보에 연결됨 | 기존 후보에 대조. 새 수신 후보를 중복 생성하지 않음 |
| 기존 M의 읽음·라벨 변경 | 새 수신 없이 읽음 표시 또는 INBOX 복귀만 발생 | 신규 수신 후보 추가 없음. 기존 업무 상태도 유지 |
| watch 성공 초기 알림 | 구독 성공 신호만 있고 새 수신 근거는 없음 | 초기 알림 자체로 신규 후보를 만들지 않음 |
| 최초 연결에서 과거 메일 조회 | 기준선 이전의 메시지로 확인됨 | 과거 이관 정책으로 분리. 일괄 신규 수신 처리하지 않음 |
초기 알림도 변경 조회는 수행합니다. 시작 기준선 이후 실제 수신이 확인되면 같은 정책으로 후보를 처리하며, 초기 알림이라는 이유로 조회 결과 전체를 버리지 않습니다. 발신·임시저장·가져오기 표본도 추가하세요. 필드 모양이 같다는 이유로 신규 수신을 확정하면 안 됩니다. 같은 메일을 원문과 일반 필드·변경 유형에서 거듭 봐도 수신 후보는 중복 생성하지 않으며, 별도 요청의 분리·병합은 후속 업무 검토에서 결정합니다.
알림이 없는 기간과 변경 기록 만료는 어떻게 다루나요?#
알림이 없다는 사실로 수신이 없었다고 답하지 않습니다. 구독 만료와 변경 조회의 마지막 성공 범위를 확인하고, 보완 조회와 원천 대사로 확인하지 못한 구간을 찾습니다. 실패한 구간은 미확인으로 남깁니다.
Gmail push 안내는 구독 갱신이 필요하고 알림이 지연되거나 누락될 수 있으며, 알림이 없는 경우 주기적인 변경 조회를 보완책으로 제시합니다. 갱신 성공은 이전 미처리 구간이 모두 처리됐다는 증거가 아닙니다. 구독 상태·수집 범위·후속 후보의 확인 상태를 따로 점검합니다.
Google의 Gmail 동기화 공식 안내는 변경 기록의 유효 범위를 벗어난 startHistoryId로 조회해 HTTP 404가 반환되면 전체 동기화가 필요하다고 설명합니다. 안내는 2026년 9월 15일 UTC 갱신됐고 2026년 10월 26일 확인했습니다.
재동기화는 허용된 범위의 현재 자료를 다시 대조하는 과정입니다. 이미 삭제된 과거 메일과 모든 업무 요청의 완전 복원을 보장하지 않습니다. 확인하지 못한 기간·자료를 예외로 남기고, 기존 확정 업무를 삭제하거나 현재 다시 보인 과거 메일을 모두 신규 업무로 만들지 않습니다.
수신 자동화 인수표에는 어떤 증거를 넣나요?#
공급자 변경 유형과 합의한 신규 수신 정책, 실제 원문·후보 연결을 함께 대조합니다. 정상 메일만 처리하는 시연으로는 읽음·라벨·최초 연결의 오생성을 찾기 어렵습니다. 중단·접근 실패도 결과로 보이게 합니다.
| 인수 항목 | 넣을 표본·기록 | 통과 또는 보류 조건 |
|---|---|---|
| 범위와 시작 | 계정·권한·기준선·과거 이관·대상/제외 정책 | 처음 조회한 자료와 신규 수신을 구별. 연결 중 새 수신도 대사 |
| 알림과 실제 메일 | 초기 알림·여러 메시지·같은 메시지 재처리 | 알림 수로 후보 수를 정하지 않고 메시지별 연결 확인 |
| 변경 유형 | 추가·읽음/라벨·발신·임시저장·가져오기 | 수신 근거 없는 항목은 제외/보류. 기존 확정 업무를 덮어쓰지 않음 |
| 조회 완결성 | 후속 페이지·오류/제한·알림 없는 기간의 보완 조회 | 일부 조회를 전체 완료나 요청0건으로 표시하지 않음 |
| 기록 만료·재동기화 | 만료 응답·현재 자료·기존 후보/업무·불명 기간 | 과거 자료 신규화·기존 업무 삭제 없이 예외와 대사 근거 보존 |
| 원문 접근과 검토 | 원문 미조회·권한 회수·검토 담당자·수동 처리 | 요약·후보·알림도 허용 범위 적용. 실패를 업무 완료로 바꾸지 않음 |
원문을 아직 확인하지 못했다면 요약·기한·담당자를 채워 넣지 않습니다. 권한 밖 메일을 공용 후보 목록이나 알림에 복제하지 않고, 담당자가 수동으로 확인할 범위와 책임을 남깁니다. 분류·초안·외부 발송의 경계는 AI 이메일 비서 구축 가이드에서 이어 확인하세요.
알파카랩스와 어떤 구축 범위를 협의할 수 있나요?#
알파카랩스의 공개 업무 자동화 서비스는 API 접근 조건, 부분 수집·중복·누락, 재처리와 수동 전환·운영 인수 조건을 협의한다고 설명합니다. 회사의 제공 방식에 관한 자기표기이며, 특정 Gmail 커넥터가 기본 제품 기능이거나 이 글의 설계를 고객에게 납품했다는 뜻은 아닙니다.
메일 공급자와 접근 범위, 신규 수신·과거 이관·라벨 진입 정책부터 확인합니다. 인수표 협의는 신규 구축 제안이며 모든 메일 서비스의 연동 가능성이나 상시 운영·무누락을 보장하지 않습니다. 실제 원본 접근과 자동 처리 범위는 권한·운영 조건을 확인한 뒤 정합니다.
Gmail 수신 자동화 검수에서 자주 묻는 질문#
- Gmail 알림의 messageId로 메일 원문을 찾으면 되나요?
- Pub/Sub 알림의 messageId는 Gmail 메일 식별자와 다릅니다. 알림의 메일함·변경 기준으로 변경 내역을 조회하고 실제 Gmail 메시지 식별자를 확인해야 합니다. 알림 식별자를 업무의 고유 키로 사용하지 않습니다.
- messagesAdded에 있으면 모두 신규 수신 업무인가요?
- 메일함에 추가된 메시지라는 사실부터 확인한 것입니다. 발신·임시저장·가져오기와 수신 범위를 구분하고 실제 원문과 업무 대상 여부를 검토합니다. 신규 수신 메일도 요청이 없거나 여러 요청을 포함할 수 있어 업무 한 건으로 바로 확정하지 않습니다.
- 읽음 표시나 INBOX 복귀에도 새 업무를 만드나요?
- 이 글의 신규 수신 정책에서는 기존 메일의 읽음·라벨 변경을 새 수신으로 세지 않습니다. 특정 라벨에 들어오면 업무를 시작하는 정책도 가능하지만, 별도 시작 조건과 재진입 규칙을 정해야 합니다. 메일의 읽음 상태로 사람이 확정한 업무 완료 상태를 덮어쓰지 않습니다.
- 처음 Gmail을 연결하면 기존 메일을 모두 신규 처리하나요?
- 최초 동기화 범위와 운영 시작 기준선을 먼저 정합니다. 과거 메일 이관과 기준선 이후의 신규 수신을 나눠 검수하고, 처음 조회됐다는 이유만으로 과거 메일을 전부 신규 업무화하지 않습니다. 연결 중 도착한 메일이 빠지는지도 별도로 확인합니다.
- 변경 기록이 만료돼도 재동기화하면 모든 요청이 복구되나요?
- 재동기화로 현재 접근 가능한 자료를 다시 대조할 수 있지만 이미 사라진 과거 메일과 모든 요청의 완전 복원을 보장하지는 않습니다. 확인하지 못한 기간·자료를 예외로 남기고 기존 확정 업무와 대사합니다. 수집 실패를 요청 없음이나 완료로 바꾸지 않습니다.