교육 문의커뮤니티 입장하기

Gmail API로 할 수 있는 일: 메일 조회부터 자동화까지

Gmail API의 메시지, 대화, 라벨, 초안 기능과 각 기능에 필요한 권한을 업무 예시로 설명합니다. 목록 응답을 읽는 법, 공식 Python 예제로 계정을 처음 연결하는 순서, 막혔을 때 볼 곳을 정리했습니다.

아직 읽은 기록이 많지 않은 글이에요
Share
Gmail API로 할 수 있는 일: 메일 조회부터 자동화까지 대표 이미지
목차
  1. API와 권한부터 구분합니다
  2. 일곱 종류로 기능을 나눠 봅니다
  3. 목록 조회 응답을 읽는 법
  4. 만들 수 있는 도구 다섯 가지
  5. 실제 계정 연결은 공식 읽기 예제로 시작합니다
  6. 막혔을 때 확인할 순서
  7. Sources
  8. 3줄 요약

세 줄로 먼저 읽기

  1. Gmail API는 사용자가 동의 화면에서 허용한 권한 범위 안에서 프로그램이 메일을 조회하고 라벨을 붙이거나 초안을 만들어 발송하게 하는 연결 방식입니다.
  2. messages.list는 메시지 ID와 대화 ID만 돌려주므로 제목과 본문은 그 ID로 messages.get을 한 번 더 호출해야 받습니다.
  3. 읽기만 하는 도구는 gmail.readonly 권한이면 충분하고, 초안 권한인 gmail.compose에는 발송도 들어 있어 초안만 만드는 앱은 코드에서 발송 경로를 빼 둡니다.

아침마다 메일함을 열어 할 일을 추리고, 같은 종류의 문의에 비슷한 답장을 쓰고 있다면 그중 일부는 프로그램에 맡길 수 있습니다. Gmail API는 이런 도구를 만들 때 프로그램이 메일을 읽고, 분류 표시를 붙이고, 초안을 만들고, 발송하게 해 주는 통로입니다. 내용을 이해해 요약하는 일은 Gmail API가 아니라 따로 붙이는 AI가 맡습니다.

이 글은 Gmail API로 할 수 있는 일을 종류별로 나누고, 각 기능에 필요한 권한과 응답을 읽는 법, 실제 계정에 처음 연결하는 순서를 다룹니다.

API와 권한부터 구분합니다

API는 프로그램이 다른 서비스에 요청을 보내고 결과를 받는 연결 방식입니다. 사람이 Gmail 화면에서 클릭하던 일을, 프로그램은 정해진 형식의 요청을 보내 대신 처리합니다.

Gmail API는 웹 요청 방식인 REST를 씁니다. 기본 주소는 https://gmail.googleapis.com이고, 메일 목록이나 라벨처럼 작업 대상에 따라 뒤의 경로가 달라집니다. 자세한 용어는 REST API 설명에서 이어집니다.

메일함에 접근할 때는 Gmail 비밀번호를 쓰지 않습니다. OAuth 2.0이라는 절차로 사용자가 동의 화면에서 앱의 접근 범위를 허용하면, 앱은 그 범위만큼 쓸 수 있는 토큰을 받습니다. 이 접근 범위를 스코프(scope)라고 부릅니다. 대표 스코프 네 가지가 허용하는 일은 이렇습니다.

Gmail 스코프별로 허용되는 일

스코프메일 읽기발송메일 변경라벨, 휴지통
gmail.readonly제공제공하지 않음제공하지 않음
gmail.send제공하지 않음제공제공하지 않음
gmail.compose(초안 관리)제공하지 않음제공제공하지 않음
gmail.modify제공제공제공
스코프 주소의 마지막 부분만 적었습니다. gmail.modify도 휴지통을 건너뛰는 즉시 영구 삭제는 할 수 없습니다.

가장 놓치기 쉬운 줄은 gmail.compose입니다. 이름은 초안 관리지만 발송도 허용하므로, 초안만 만드는 앱은 코드에서 발송 경로를 빼 둬야 합니다. 권한은 넓게 한 번에 받기보다 쓰는 메서드마다 필요한 스코프를 맞춰 요청합니다. 다른 사람에게 배포하는 공개 앱은 요청하는 스코프에 따라 구글의 앱 검증 절차를 거칩니다.

일곱 종류로 기능을 나눠 봅니다

리소스는 API에서 다루는 대상이고, 메서드는 그 대상에 하는 작업입니다. 예를 들어 메시지라는 대상에는 목록을 가져오는 list와 한 통의 상세 내용을 가져오는 get이 있습니다. 이 글에서는 users.messages.list를 messages.list처럼 앞의 users를 빼고 적습니다. ID는 메시지나 대화를 구별하는 식별값입니다.

공식 문서는 첨부파일과 설정 하위 항목까지 따로 나누지만, 업무에서 다루는 대상으로 묶으면 일곱 가지입니다.

종류다루는 대상업무 예시
Messages메일 한 통특정 문의의 본문 읽기
Threads같은 대화에 속한 메일 묶음문의와 후속 답변 함께 보기
Labels메일에 붙이는 분류 표시견적 요청 메일에 표시 붙이기
Drafts아직 보내지 않은 메일답변 초안 검토하기
History메일함 변경 기록지난번 확인 이후 바뀐 메일만 가져오기
Users사용자 프로필과 알림 구독연결한 계정과 알림 설정 보기
Settings필터, 서명, 전달 같은 설정반복되는 분류 규칙 만들기

Messages: 목록과 상세 내용은 따로 받습니다

작업하는 일
messages.list조건에 맞는 메시지 ID 목록 조회
messages.get메시지 한 통의 상세 내용 조회
messages.attachments.get첨부파일 데이터 조회
messages.modify / batchModify한 통 또는 여러 통의 라벨 변경
messages.send메일 발송
messages.trash / untrash휴지통 이동 또는 복원
messages.delete / batchDelete한 통 또는 여러 통 영구 삭제
messages.insert / import메시지를 메일함에 넣기

insert와 import는 메일함에 메시지를 넣는 작업이고, 다른 사람에게 보내지 않습니다. 둘의 차이는 검사 과정입니다. import는 일반 수신 메일처럼 검사와 분류를 거치고, insert는 그 과정 대부분을 건너뜁니다.

Threads: 대화 단위로 묶입니다

threads.list와 threads.get은 같은 대화에 속한 메일 묶음을 조회하고, modify, trash, untrash, delete로 묶음 전체를 관리합니다.

대화 묶음은 답장으로 이어진 메일 단위입니다. 한 고객과 여러 주제로 주고받은 메일은 대화가 여러 개로 나뉩니다. 그래서 고객별 이력을 만들 때는 대화 ID가 아니라 이메일 주소처럼 고객을 구별할 기준을 따로 정합니다. 대화 ID를 고객 ID로 쓰면 다른 주제의 문의가 이력에서 빠집니다.

Labels: 한 메일에 여러 표시를 붙입니다

라벨은 메일에 붙이는 분류 표시입니다. 폴더와 달리 한 메일에 라벨 여러 개를 붙일 수 있습니다. INBOX, UNREAD 같은 시스템 라벨과 사용자가 직접 만든 라벨이 있습니다.

labels.list, get, create, update, patch, delete는 라벨 자체를 만들고 고치는 작업입니다. 이미 받은 메일에 라벨을 붙이는 일은 messages.modify가 합니다. 라벨을 삭제하면 메일에서 그 표시만 사라지고 메일은 그대로 남습니다.

Drafts: 저장과 발송을 나눕니다

초안을 만드는 작업과 보내는 작업은 별개입니다. 고객 답변 도구라면 그 사이에 사람이 검토하는 단계를 둡니다.

답변 초안을 만들고 보내는 순서

  1. 1. drafts.create문의를 읽고
    답변 초안 저장
  2. 2. 사람 검토수신자, 금액, 약속한
    날짜를 원문과 대조
  3. 3. drafts.update고칠 곳이 있으면
    초안 내용 교체
  4. 4. drafts.send승인한 초안만
    발송

초안을 확인하는 drafts.list와 drafts.get, 지우는 drafts.delete도 있습니다. 첫 버전은 초안 저장까지만 만들고, 발송은 사람이 Gmail 화면에서 초안을 열어 직접 하는 방식으로 시작할 수도 있습니다.

History와 Users: 변경 알림을 받은 뒤 한 번 더 조회합니다

users.getProfile은 연결한 계정의 이메일 주소와 메시지 수를 조회합니다. users.watch는 메일함 변경 알림을 구독하고, users.stop은 구독을 멈춥니다.

푸시 알림은 메일함이 바뀌었을 때 구글 서버가 먼저 앱에 알려 주는 방식입니다. Gmail은 알림 전달에 Google Cloud Pub/Sub 서비스를 씁니다. 알림에는 메일 본문이 없고 이메일 주소와 historyId만 들어 있으므로, 바뀐 메일을 읽기까지 조회를 두 번 더 합니다.

새 메일 알림에서 본문까지

  1. 1. 알림 수신Pub/Sub로 이메일 주소와
    historyId 도착
  2. 2. history.list저장해 둔 historyId 이후
    바뀐 내용 조회
  3. 3. messages.get새로 온 메시지 ID로
    본문 조회
  4. 4. watch 갱신최소 7일마다,
    공식 권장은 매일

알림은 늦게 오거나 빠질 수 있으므로 정해진 간격으로 history.list를 직접 호출해 빠진 변경을 채웁니다. historyId는 날짜가 아니라 변경 기록의 위치를 가리키는 값입니다. 너무 오래된 값으로 조회하면 404 오류가 나는데, 이때는 같은 요청을 반복하지 않고 필요한 범위의 메시지를 처음부터 다시 받아 앱이 가진 정보와 메일함 상태를 맞춥니다. 이 작업을 동기화라고 합니다.

Settings: 계정 종류에 따라 쓸 수 있는 범위가 다릅니다

Settings는 필터, 서명과 발신 별칭, 부재중 응답, 자동 전달, IMAP과 POP 설정을 다룹니다. IMAP과 POP는 아웃룩 같은 메일 프로그램이 메일을 받아 오는 통신 방식입니다.

위임과 이메일 암호화 설정은 계정 종류에 따라 쓸 수 있는 범위가 다릅니다. 예를 들어 위임 생성 API는 같은 Google Workspace 조직의 사용자 사이에서만 쓸 수 있고, 관리자가 조직 범위 권한을 위임한 서비스 계정이 있어야 호출할 수 있습니다. 서비스 계정은 사람이 아니라 프로그램이 인증할 때 쓰는 계정입니다.

settings.filters.create는 보낸 사람이나 제목 같은 조건과 그에 따른 행동을 정한 Gmail 필터를 만듭니다. 필터는 정해진 조건으로만 나누므로, 본문 내용을 보고 나누려면 앱이 본문을 읽어 AI로 분류한 뒤 messages.modify로 라벨을 붙입니다.

목록 조회 응답을 읽는 법

messages.list로 검색하면 응답에 메시지 ID 목록이 옵니다. JSON은 항목 이름과 값을 짝지어 데이터를 담는 형식이고, 대괄호 [] 안에 여러 항목을 모은 부분을 배열이라고 합니다. 청구서 메일을 찾는 요청을 보냈다면 응답은 이런 모양입니다.

messages.list 응답
GET /gmail/v1/users/me/messages?q=subject:청구서
{
"messages": [
{"id": "mail-a", "threadId": "thread-1"},
{"id": "mail-b", "threadId": "thread-1"}
],
"nextPageToken": "page-2",
"resultSizeEstimate": 5
}
제목과 본문은 없고 ID만 옵니다
설명을 위해 만든 화면입니다. 실제 ID는 영문과 숫자가 섞인 긴 문자열입니다.

이 응답에서 읽을 것은 네 가지입니다. 이번에 받은 메시지는 배열 안의 두 통이고, 두 통의 threadId가 같으니 같은 대화에 속합니다. resultSizeEstimate의 5는 전체 결과 수의 추정값이라 지금 받은 개수와 다릅니다. nextPageToken이 있으면 다음 페이지가 남았다는 뜻이고, 같은 조건의 다음 요청에 이 값을 pageToken으로 넣어 이어 받습니다. 토큰이 없으면 마지막 페이지입니다.

본문을 요약하려면 mail-a라는 메시지 ID로 messages.get을 호출합니다. 메시지 ID 대신 대화 ID인 thread-1을 넣으면 상세 조회가 실패합니다.

검색에 맞는 메일이 없으면 요청은 성공해도 응답에 "resultSizeEstimate": 0만 오고 messages 배열이 아예 없습니다. 이 경우를 인증 실패로 처리하지 않도록, 코드는 먼저 응답에 error 항목이 있는지 보고, 없으면 messages가 있는지 확인한 뒤 첫 항목을 읽습니다. 배열이 항상 있다고 보고 첫 항목을 바로 읽으면 결과가 0건인 날 프로그램이 멈춥니다.

만들 수 있는 도구 다섯 가지

업무에서 흔히 만드는 도구와 처리 순서, 먼저 검수할 내용은 이렇습니다.

도구처리 순서먼저 검수할 내용
아침 메일 요약목록 조회 → 상세 읽기 → 요약기한과 할 일을 원문대로 남겼는지
문의 자동 분류상세 읽기 → 규칙이나 AI로 분류 → 라벨 적용애매한 문의를 사람이 볼 대상으로 남기는지
답변 초안 도구문의 읽기 → 초안 작성 → 승인 → 발송수신자와 약속, 금액이 맞는지
간단한 고객 관리대화 조회 → 고객 식별 → 상태 기록다른 고객을 같은 사람으로 합치지 않는지
승인된 메일 이전원본 조회 → 대상 계정에 넣기 → 대조누락과 중복이 없고 첨부파일까지 옮겨졌는지

도구마다 요청할 스코프가 다릅니다. 앞에서 본 권한 표에 맞춰 보면 읽기만 하는 도구는 가장 좁은 권한으로 충분합니다.

도구별로 필요한 권한

도구메일 읽기gmail.readonly라벨 변경gmail.modify초안과 발송gmail.compose
아침 메일 요약제공제공하지 않음제공하지 않음
문의 자동 분류제공제공제공하지 않음
답변 초안 도구제공제공하지 않음제공
간단한 고객 관리제공제공하지 않음제공하지 않음
문의 자동 분류는 gmail.modify 하나로 읽기와 라벨 변경을 함께 받을 수 있습니다.

요약과 AI 분류는 Gmail API 밖에서 하는 처리입니다. 본문을 외부 AI 서비스로 보낸다면 그 서비스의 데이터 전송과 보관 방식이 회사 기준에 맞는지도 봅니다. 결과를 Slack이나 Notion으로 보내는 기능도 각 서비스의 API와 권한이 따로 필요합니다.

회사 계정의 메일을 다른 계정으로 옮기는 이전 도구는 회사 보안 정책이 허용한 자료와 계정에서만 씁니다. 옮기기 전에 원본을 보존하고, 문제가 생기면 되돌릴 방법도 정해 둡니다.

도구가 실제로 시간을 줄였는지는 직접 측정합니다. 조회와 생성에 걸린 시간에 잘못 분류된 메일을 고친 시간과 초안 검토 시간까지 더해, 같은 일을 손으로 했을 때와 비교합니다.

실제 계정 연결은 공식 읽기 예제로 시작합니다

Python은 이 예제 코드를 작성한 프로그래밍 언어입니다. Google의 Python 시작 예제는 연결한 계정의 라벨 이름을 터미널에 출력하는 예제입니다. Python 3.10.7 이상과 Gmail 계정, Google Cloud 프로젝트가 필요합니다. Cloud 프로젝트는 API 사용 설정과 앱 인증 정보를 관리하는 단위입니다.

공식 Python 예제로 첫 연결까지

  1. 1. API 사용 설정Cloud 프로젝트에서
    Gmail API 켜기
  2. 2. OAuth 동의 화면앱 이름과 대상 정하고
    테스트 사용자 추가
  3. 3. 인증 정보 만들기데스크톱 앱 유형으로 만들고
    credentials.json 저장
  4. 4. 라이브러리 설치예제 페이지의
    설치 명령 실행
  5. 5. 예제 실행브라우저에서 동의하면
    터미널에 라벨 목록 출력

라이브러리는 API 호출과 인증에 필요한 기능을 모은 코드 묶음입니다. 2단계의 대상 선택지는 계정 종류에 따라 다릅니다. Google Workspace 조직 계정은 조직 내부 사용자로 한정할 수 있고, 개인 Gmail 계정은 외부 사용자로 두고 자기 계정을 테스트 사용자로 넣습니다.

5단계에서 터미널에 INBOX, SENT 같은 라벨 이름이 나오고, 연결하려던 계정의 라벨과 같으면 인증과 조회에 성공한 것입니다. 이 예제는 라벨 이름만 출력하므로 메일 본문은 나오지 않습니다. 본문을 조회하려면 예제의 라벨 조회 부분을 messages.list와 messages.get 호출로 바꿉니다.

예제 폴더의 credentials.json은 앱 인증 설정이고, 처음 실행할 때 만들어지는 token.json에는 사용자가 허용한 권한으로 접근하는 토큰이 저장됩니다. 두 파일은 공개 저장소나 질문 글에 올리지 않고, 오류를 물어볼 때는 비밀값을 지운 오류 메시지만 붙입니다.

막혔을 때 확인할 순서

연결 단계에서 자주 막히는 지점과 먼저 볼 곳을 모았습니다.

증상먼저 볼 곳
로그인이나 동의 단계에서 막힘고른 계정, 앱 대상과 테스트 사용자, 조직 관리자 정책
인증 정보 파일을 찾지 못함예제를 실행한 폴더와 파일 이름
라벨은 나오는데 메일 본문은 없음실행한 것이 라벨 조회 예제인지
검색 결과가 0건연결한 계정과 검색 조건, 조건에 맞는 메일이 실제로 있는지
상세 조회 실패메시지 ID 대신 대화 ID를 넣었는지
권한 부족 오류요청 메서드에 필요한 스코프와 실제로 동의한 범위
변경 알림이 끊김watch 갱신 시각과 이력 동기화 상태

예제를 고쳐 메일을 읽거나 라벨을 바꾸려고 하면 권한 부족 오류가 자주 납니다. 원인은 대개 예전 token.json입니다. 코드의 스코프를 바꿔도 이 파일의 토큰에는 처음 동의한 좁은 권한만 남아 있습니다.

스코프를 바꾼 뒤 예제 실행
python3 quickstart.py
HttpError 403: Request had insufficient authentication scopes.
토큰에 남은 권한이 요청 메서드에 필요한 스코프보다 좁음
rm token.json && python3 quickstart.py
브라우저 동의 화면이 다시 열리고, 새 권한에 동의하면 요청이 실행됩니다.
설명을 위해 만든 화면입니다. 공식 예제 코드도 스코프를 바꾸면 token.json을 지우라고 안내합니다.

권한 오류가 났다고 스코프를 한꺼번에 넓히면 원인을 놓칩니다. 어떤 요청에서 어떤 오류가 났는지 먼저 적고, 그 메서드에 필요한 스코프 하나만 추가합니다. 연결에 성공한 뒤에도 다음 페이지를 끝까지 받는지, 같은 메일을 두 번 처리하지 않는지, 빠진 메일을 다시 채우는지 시험해야 자동화에 쓸 수 있습니다. 그래서 첫 도구는 발송 없이 읽기만 하는 도구로 만들고, 결과가 원문과 맞는지 며칠 지켜본 뒤 라벨 변경과 초안 기능을 더합니다.

Sources

3줄 요약

  1. Gmail API는 사용자가 동의 화면에서 허용한 권한 범위 안에서 프로그램이 메일을 조회하고 라벨을 붙이거나 초안을 만들어 발송하게 하는 연결 방식입니다.

  2. messages.list는 메시지 ID와 대화 ID만 돌려주므로 제목과 본문은 그 ID로 messages.get을 한 번 더 호출해야 받습니다.

  3. 읽기만 하는 도구는 gmail.readonly 권한이면 충분하고, 초안 권한인 gmail.compose에는 발송도 들어 있어 초안만 만드는 앱은 코드에서 발송 경로를 빼 둡니다.

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

messages.list 응답에 id와 threadId만 있습니다. 본문이 필요하면 다음에 무엇을 하나요?

이 글이 도움이 되었나요?

이 글 다음 배우기AI 업무 자동화 입문입문 코스 · 3편

메일, 회의록, 리포트처럼 반복되는 일을 AI로 자동화하는 순서와 안전장치를 다룹니다

  1. 1AI 업무 자동화 뜻과 규칙 자동화와 다른 점
  2. 2n8n 이해하기, 노드로 잇는 자동화와 셀프호스팅
  3. 3회의록 자동화, 녹음과 받아쓰기와 요약과 배포
코스 전체 보기 →
같은 주제의 다음 단계Google Workspace Studio 사용법: 시작 조건, 단계, 변수로 첫 자동화 만들기 →

Workspace Studio의 시작 조건, 단계, 변수를 주간 리포트 메일 정리 플로우로 설명합니다. 테스트 실행이 실제로 하는 일, 활동 탭에서 결과를 대조하는 순서, 계정 조건과 한도를 정리했습니다.