인증 및 설정
Gmail 통합은 Google Cloud Platform을 통한 OAuth 2.0 인증이 필요합니다. 조직은 Google Cloud Console에서 프로젝트를 생성하고, Gmail API를 활성화하며, OAuth 동의 화면을 구성해야 합니다. 이 통합은 개인 Gmail 계정과 Google Workspace(구 G Suite) 엔터프라이즈 계정을 모두 지원합니다. 인증 토큰은 안전하게 저장되고 지속적인 접근을 유지하기 위해 자동으로 새로고침됩니다.필요한 API 범위
- gmail.readonly: 이메일 및 설정에 대한 읽기 전용 접근 권한.
- gmail.send: 사용자를 대신하여 이메일을 보냅니다.
- gmail.compose: 초안 이메일을 생성하고 관리합니다.
- gmail.modify: 이메일 읽기, 작성, 보내기 및 수정에 대한 완전한 접근 권한.
- gmail.labels: 이메일 라벨 및 카테고리를 관리합니다.
사용 가능한 작업
모든 필요한 권한이 구성되면 툴킷은 다음 작업을 활성화합니다.이메일 관리
- 이메일 검색: Gmail 쿼리 구문(from:, to:, subject:, has:attachment, is:unread 등)을 사용한 고급 검색.
- 이메일 콘텐츠 가져오기: 헤더, 본문(일반 텍스트/HTML) 및 첨부 파일 목록이 포함된 전체 이메일을 검색합니다.
- 이메일 보내기: 여러 수신자, CC/BCC, 첨부 파일 및 HTML 콘텐츠로 새 이메일을 작성하고 보냅니다.
- 이메일 답글: 대화 기록 및 스레딩을 유지하면서 기존 스레드에 답글을 보냅니다.
- 이메일 전달: 선택적 추가 코멘트와 함께 메시지를 다른 수신자에게 전달합니다.
- 첨부 파일 가져오기: 처리 또는 스토리지를 위해 이메일 첨부 파일을 다운로드합니다.
- 이메일 삭제: 이메일을 휴지통으로 이동하거나 휴지통에서 영구적으로 삭제합니다.
- 이메일 보관: 모든 메일에서 유지하면서 받은편지함에서 제거합니다.
- 스팸으로 표시: 원치 않는 이메일을 보고하고 스팸 폴더로 이동합니다.
- 중요/별표 표시: 쉽게 검색할 수 있도록 중요한 이메일에 플래그를 지정합니다.
초안 관리
- 초안 생성: 보내지 않고 이메일 작성을 초안으로 저장합니다.
- 초안 업데이트: 기존 초안의 콘텐츠, 수신자 또는 첨부 파일을 수정합니다.
- 초안 보내기: 이전에 생성된 초안 이메일을 보냅니다.
- 초안 목록: 저장된 모든 초안 이메일을 봅니다.
- 초안 삭제: 초안 폴더에서 초안 이메일을 제거합니다.
라벨 작업
- 라벨 목록 가져오기: 시스템 및 사용자 정의 라벨을 포함한 모든 사용 가능한 라벨을 가져옵니다.
- 라벨 생성: 이메일 구성을 위한 사용자 정의 라벨을 생성합니다.
- 라벨 적용: 이메일에 하나 또는 여러 라벨을 추가합니다.
- 라벨 제거: 이메일에서 라벨을 제거합니다.
- 라벨 이름 변경: 더 나은 구성을 위해 라벨 이름을 변경합니다.
- 라벨 삭제: 사용자 정의 라벨을 제거합니다(이메일은 그대로 유지).
스레드 작업
- 스레드 가져오기: 모든 메시지가 포함된 전체 대화 스레드를 검색합니다.
- 스레드 목록 가져오기: 검색 기준에 따라 대화 스레드를 조회합니다.
- 스레드 수정: 스레드의 모든 이메일에 일괄 작업을 적용합니다.
상태 관리
- 읽음으로 표시: 단일 또는 여러 이메일의 읽음 상태를 업데이트합니다.
- 읽지 않음으로 표시: 나중에 확인할 수 있도록 이메일을 읽지 않음으로 표시합니다.
- 이메일 휴지통: 이메일을 휴지통 폴더로 이동합니다.
- 이메일 복구: 휴지통에서 받은편지함으로 이메일을 복원합니다.
구성 옵션
- 쿼리 필터: 검색에 대한 기본 필터를 설정합니다(예: 최근 30일만 검색).
- 최대 결과: 쿼리당 검색할 최대 이메일 수를 구성합니다(기본값 50, 최대 500).
- 스팸/휴지통 포함: 검색에 스팸 및 휴지통 폴더를 포함할지 여부.
- 첨부 파일 처리: 다운로드된 첨부 파일에 대한 크기 제한 및 바이러스 검사를 설정합니다.
- 기본 라벨: 에이전트가 보낸 이메일에 자동으로 라벨을 적용합니다.
- 스레드 모드: 답글에 대한 자동 스레드 그룹화를 활성화/비활성화합니다.
사용 사례
- 지능형 받은편지함 관리: 콘텐츠 분석을 기반으로 수신 이메일을 자동으로 분류, 라벨 지정 및 우선순위를 지정합니다.
- 리드 추출: 이메일에서 연락처 정보를 스캔하고, 리드를 추출하며, CRM 시스템을 채웁니다.
- 자동 응답: KB 지식을 사용하여 일반적인 문의에 대한 상황에 맞는 응답을 생성합니다.
- 이메일 모니터링: 특정 키워드나 발신자를 감시하고 워크플로우 또는 알림을 트리거합니다.
- 뉴스레터 관리: 프로모션 이메일을 자동으로 파일링, 요약하거나 구독 취소합니다.
- 고객 지원: 콘텐츠 분류를 기반으로 지원 이메일을 적절한 팀으로 라우팅합니다.
- 경비 추적: 이메일에서 영수증을 추출하고, 첨부 파일을 처리하며, 회계 시스템에 기록합니다.
- 회의 조율: 회의 초대 이메일을 분석하고 캘린더 시스템과 동기화합니다.
모범 사례
- Gmail 쿼리 구문 사용: 정확한 이메일 필터링을 위해 고급 검색 연산자를 활용합니다.
- 일괄 작업: API 호출을 줄이기 위해 여러 이메일을 단일 작업으로 처리합니다.
- API 할당량 준수: Gmail API에는 일일 할당량 제한이 있습니다(Google Workspace의 경우 일일 10억 할당량 단위).
- 지수 백오프 구현: 재시도 로직으로 속도 제한을 우아하게 처리합니다.
- 스레드 안전 답글: 대화 컨텍스트를 유지하기 위해 답글 시 항상 스레드 ID를 사용합니다.
- 라벨 구성: 자동 분류를 위한 명확한 라벨 계층 구조를 생성합니다.
API 할당량 고려 사항
Gmail API는 할당량 시스템을 사용하며, 서로 다른 작업에 대해 서로 다른 비용이 발생합니다. 일반적인 비용: 이메일 보내기(100단위), 메시지 가져오기(5단위), 메시지 목록(1단위). 한도를 초과하지 않도록 Google Cloud Console에서 사용량을 모니터링합니다. 고용량 애플리케이션의 경우 Google을 통해 할당량 증가를 요청하세요.일반적인 문제 및 해결 방법
- 할당량 초과: 캐싱 및 일괄 작업을 구현하여 API 호출을 줄입니다. 필요한 경우 할당량 증가를 요청하세요.
- Invalid Grant 오류: 토큰이 만료되었거나 취소되었습니다. OAuth 흐름을 통해 사용자를 다시 인증하세요.
- 권한 누락: OAuth 동의 시 필요한 모든 범위가 요청되었는지 확인합니다.
- 첨부 파일 다운로드 실패: 대용량 첨부 파일은 시간 초과될 수 있습니다. 5MB 이상 파일에는 스트리밍 다운로드를 사용하세요.