Gmail API로 할 수 있는 일: 메일 조회부터 자동화까지
Gmail API의 메시지, 대화, 라벨과 초안 기능을 업무 예시로 설명합니다. 가상 응답을 읽으며 목록과 본문 조회의 차이를 익히고, 실제 연결을 시작할 때 확인할 권한과 결과를 살펴봅니다.
목차
세 줄로 먼저 읽기
이번 방문에서 한 편은 바로 볼 수 있습니다.
아침마다 메일을 확인해 할 일을 정리한다면, 어떤 부분을 프로그램에 맡길 수 있을까요? Gmail API는 메일을 읽고 정리하거나 초안을 만드는 도구를 구현할 때 사용합니다. 다만 API 자체가 내용을 이해해 요약하는 AI는 아닙니다.
이 글의 첫 목표는 메일 목록에서 필요한 메시지를 찾고, 상세 내용을 읽는 순서를 설명하는 것입니다. 아래 가상 응답 연습은 가입이나 계정 연결 없이 가능합니다. 실제 연결은 그다음 단계로 구분합니다.
API와 권한부터 구분합니다
API는 프로그램이 다른 서비스에 요청하고 결과를 받는 연결 방식입니다. Gmail 화면에서 사람이 클릭하는 대신, 프로그램이 정해진 요청을 보내는 상황을 생각하면 됩니다.
Gmail API는 웹 요청 방식인 REST를 사용합니다. 기본 주소는 https://gmail.googleapis.com이며, 메일 목록이나 라벨처럼 작업 대상에 따라 뒤의 경로가 달라집니다. 자세한 용어는 REST API 설명에서 이어 볼 수 있습니다.
OAuth 2.0은 사용자가 앱의 접근 범위를 허용하는 절차에 쓰입니다. 스코프(scope)는 읽기나 발송처럼 앱이 요청하는 권한 범위입니다. Gmail 비밀번호를 코드에 넣거나 API 키 하나만 발급한다고 메일함에 접근하는 구조가 아닙니다.
| 권한 예시 | 허용하는 대표 작업 | 주의할 구분 |
|---|---|---|
gmail.readonly | 메일과 설정 읽기 | 메일 변경이나 발송 권한이 아님 |
gmail.send | 메일 발송 | 본문을 읽는 권한과 별개 |
gmail.compose | 초안 관리와 발송 | 초안만 허용하는 권한은 아님 |
gmail.modify | 읽기, 작성, 발송과 메일 변경 | 휴지통을 건너뛴 즉시 영구 삭제는 제외 |
표는 전체 스코프 주소의 마지막 부분만 표시한 것입니다. 권한을 넓게 요청하는 대신 필요한 작업과 각 메서드의 허용 스코프를 맞춥니다. 초안 생성 권한에 발송도 포함될 수 있으므로, 초안만 만드는 앱은 코드에서도 발송 경로를 제외해야 합니다. 공개 앱의 검증 요건은 개인 시험과 별도로 확인합니다. 공식 권한 목록
일곱 종류로 기능을 살펴봅니다
리소스는 API에서 다루는 대상, 메서드는 그 대상에 수행하는 작업입니다. 예를 들어 메시지라는 대상에 목록 조회인 list와 상세 조회인 get 작업이 있습니다.
이 글에서는 users.messages.list를 messages.list로 줄여 쓰는 등 앞의 users를 생략합니다. ID는 메시지나 대화를 구별하는 식별값입니다.
아래 일곱 종류는 학습을 위한 큰 분류입니다. 공식 문서는 첨부파일이나 설정 하위 항목도 별도 리소스로 나누므로 ‘정확히 일곱 개만 있다’는 뜻은 아닙니다. Gmail API 전체 참조
| 종류 | 다루는 대상 | 익숙한 업무 예시 |
|---|---|---|
| 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는 상당 부분을 건너뛰므로 같은 동작으로 취급하지 않습니다. 처음 읽기 연습에는 이 두 작업이나 삭제가 필요하지 않습니다.
messages.list의 각 항목에는 id와 threadId가 들어 있습니다. 제목과 본문이 바로 오는 것은 아닙니다. 찾은 id로 messages.get을 요청해야 상세 정보를 받습니다. 상세 응답의 본문 형식과 첨부파일 처리도 따로 확인해야 합니다. 목록 조회 응답
Threads: 사람별 고객 목록은 아닙니다
threads.list와 threads.get은 대화 묶음을 조회합니다. modify, trash, untrash, delete로 관리하는 기능도 있습니다.
한 고객과 여러 주제로 주고받은 메일이 모두 하나의 대화로 합쳐지는 것은 아닙니다. 고객별 이력을 만들려면 이메일 주소와 고객 식별 기준을 별도로 정해야 합니다. 대화 ID를 고객 ID로 사용하면 다른 문의가 빠질 수 있습니다.
Labels: 한 메일에 여러 표시를 붙입니다
라벨은 분류 표시입니다. 폴더와 비슷하게 보이지만 한 메시지에 여러 라벨을 붙일 수 있습니다. INBOX와 UNREAD 같은 시스템 라벨, 직접 만든 사용자 라벨을 구분합니다. 라벨 공식 설명
labels.list, get, create, update, patch, delete는 라벨 자체를 관리합니다. 이미 있는 메시지에 라벨을 붙이는 작업은 messages.modify 등으로 수행합니다. 라벨을 만드는 것과 메일에 적용하는 것은 다릅니다. 라벨을 삭제하면 해당 분류 표시가 제거되며, 메일 자체를 영구 삭제하는 것은 아닙니다.
Drafts: 저장과 발송을 나눕니다
drafts.create로 초안을 만들고 list와 get으로 확인하며 update로 내용을 교체합니다. 실제 발송은 drafts.send라는 별도 작업입니다. 초안을 지우는 drafts.delete도 있습니다.
고객 답변 도구의 첫 버전이라면 생성한 초안을 검토하는 단계까지 구현해 보세요. 수신자, 참조 주소, 금액과 약속한 날짜를 사람이 원문과 대조하고 승인한 뒤 발송하도록 순서를 정합니다.
History와 Users: 변경 알림 뒤에도 조회가 필요합니다
users.getProfile은 연결한 계정의 이메일 주소와 메시지 수 같은 프로필을 조회합니다. users.watch는 메일함 변경 알림을 구독하고 users.stop은 구독 알림을 중지합니다.
푸시 알림은 서버가 변경 사실을 보내는 방식입니다. Gmail은 알림 전달 서비스인 Google Cloud Pub/Sub를 사용합니다. 알림에는 메일 본문 대신 이메일 주소와 historyId가 들어 있으므로, 저장해 둔 이력 ID를 기준으로 history.list에서 변경 내용을 조회하고 필요한 메시지를 읽습니다.
watch는 최소 7일마다 갱신해야 하며 공식 문서는 매일 갱신을 권장합니다. 알림이 지연되거나 누락될 수 있어 주기적인 이력 확인도 고려해야 합니다. ‘즉시 알림이 항상 보장된다’거나 ‘한 번 설정하면 계속 된다’고 가정하지 않습니다. 푸시 알림 공식 안내
historyId는 날짜가 아니라 변경 이력을 가리키는 값입니다. 너무 오래된 값으로 조회해 범위를 벗어나면 404 오류가 날 수 있습니다. 이 경우 같은 요청을 반복하는 대신 필요한 범위의 메시지를 다시 동기화해야 합니다. 동기화는 앱이 가진 정보와 현재 메일함 상태를 맞추는 작업입니다. 동기화 안내
Settings: 계정 종류와 관리 권한을 확인합니다
필터, 서명과 발신 별칭, 부재중 응답, 자동 전달, IMAP 및 POP 설정 등을 다룹니다. IMAP과 POP는 메일 프로그램이 메일을 받아 보는 통신 방식입니다. 위임과 이메일 암호화 관련 설정도 있지만 모든 개인 계정에서 모든 기능을 똑같이 쓸 수 있는 것은 아닙니다.
예를 들어 위임 생성 API는 같은 Google Workspace 조직의 사용자 사이에서 사용하며, 관리자가 조직 범위의 권한을 위임한 서비스 계정이 필요합니다. 서비스 계정은 프로그램이 인증할 때 사용하는 계정입니다. 개인 Gmail 로그인만으로 조직 전체를 관리할 수 있다고 생각하지 않습니다. 위임 생성 조건
settings.filters.create는 조건과 행동을 정한 Gmail 필터를 만듭니다. 이것만 호출하면 AI가 맥락을 이해하는 것은 아닙니다. 본문을 AI로 분류하는 앱이라면 별도로 내용을 읽어 분류한 뒤 결과에 따라 라벨을 적용합니다. 필터 설정 안내
첫 연습: 가상 목록 응답을 읽습니다
아래 JSON은 실제 계정의 응답이 아닌 연습 자료입니다. JSON은 항목 이름과 값을 짝지어 데이터를 표현하는 형식입니다. 대괄호 [] 안에 여러 항목을 모아 둔 부분을 배열이라고 합니다. 메모장에 아래 내용을 복사하고 세 질문에 답해 보세요.
{
"messages": [
{"id": "mail-a", "threadId": "thread-1"},
{"id": "mail-b", "threadId": "thread-1"}
],
"nextPageToken": "page-2",
"resultSizeEstimate": 5
}- 지금 받은 메시지는 몇 통인가요?
- 두 메시지는 같은 대화에 속하나요?
- 이 응답만으로 본문을 요약할 수 있나요?
답은 2통, 같은 대화, 본문이 없어 아직 요약할 수 없음입니다. resultSizeEstimate는 총결과 수의 추정값이므로 현재 배열에 담긴 메시지 수와 같다고 보지 않습니다. nextPageToken이 있으면 다음 페이지가 있다는 뜻입니다. 같은 조건의 다음 요청에 이 값을 pageToken으로 전달합니다.
본문이 필요하면 먼저 mail-a라는 메시지 ID로 상세 조회를 합니다. 대화 ID인 thread-1을 메시지 ID 대신 넣지 않습니다. 실제 API에서는 예시 ID 대신 응답에서 받은 값을 사용해야 합니다.
이제 요청이 성공했지만 검색에 맞는 메일이 없는 결과도 연습합니다.
{
"resultSizeEstimate": 0
}먼저 실제 요청에서는 성공 상태인지와 error 오류 정보가 있는지 확인해야 합니다. 위 예시는 성공한 목록 응답이므로 messages가 없으면 결과가 없는 경우로 처리합니다. 곧바로 인증 실패라고 판단하지 않습니다. 배열이 항상 존재한다고 가정해 첫 항목을 읽으면 코드가 실패할 수 있습니다.
마지막으로 첫 응답에서 nextPageToken을 지워 보세요. 더 받아야 할 페이지 토큰이 없으므로 다음 페이지 요청을 하지 않는 것이 기대 동작입니다. 이어서 두 번째 메시지의 threadId만 thread-2로 바꿔 보세요. 기대 답은 메시지 2통이 서로 다른 대화에 속한다는 것입니다. 조건을 바꾼 새 예시에서도 메시지 수, 대화 묶음과 다음 동작을 스스로 적어 보세요.
만들 수 있는 도구 다섯 가지
| 아이디어 | 기본 처리 순서 | 먼저 검수할 내용 |
|---|---|---|
| 아침 메일 요약 | 목록 조회 → 상세 읽기 → 요약 | 기한과 할 일을 원문대로 남겼는지 |
| 문의 자동 분류 | 상세 읽기 → 규칙 또는 AI 분류 → 라벨 적용 | 애매한 문의를 확인 대상으로 남기는지 |
| 답변 초안 도구 | 문의 읽기 → 초안 작성 → 승인 → 발송 | 수신자와 약속, 금액이 맞는지 |
| 간단한 고객 관리 | 대화 조회 → 고객 식별 → 상태 기록 | 다른 고객을 같은 사람으로 합치지 않는지 |
| 승인된 메일 이전 | 원본 조회 → 대상 계정에 넣기 → 대조 | 누락, 중복과 첨부파일을 확인했는지 |
요약이나 AI 분류는 Gmail API 밖의 별도 처리입니다. 다른 서비스에 본문을 보낼 경우 그 전송과 보관 조건까지 확인합니다. Slack이나 Notion에 보내는 기능도 해당 서비스의 별도 API와 권한이 필요합니다.
메일을 회사 계정에서 개인 계정으로 옮길 수 있다는 기술적 가능성이 자료 반출 권한을 뜻하지는 않습니다. 이전 도구는 허용된 자료와 대상 계정으로 범위를 정하고 원본 보존 및 복구 방법을 확인한 뒤 사용합니다.
시간 절약은 직접 측정해야 합니다. 조회나 생성 시간뿐 아니라 오분류 수정과 초안 검수 시간까지 합쳐, 같은 업무를 수동으로 처리했을 때와 비교합니다.
실제 계정 연결은 공식 읽기 예제로 시작합니다
Python은 코드를 실행하는 언어입니다. Google의 Python 시작 예제는 Python 3.10.7 이상과 Gmail 계정, Google Cloud 프로젝트를 준비해 라벨 이름을 출력하는 결과를 만듭니다. Cloud 프로젝트는 API 사용 설정과 앱 인증 정보를 관리하는 단위입니다.
공식 페이지 순서에 따라 API 활성화, OAuth 설정, 데스크톱 앱 인증 정보 생성, 라이브러리 설치와 예제 실행을 진행합니다. 라이브러리는 API 호출과 인증에 필요한 기능을 모은 코드입니다. 계정 유형에 따라 OAuth 대상 선택지가 다르므로 조직 내부 사용자 설정을 개인 계정에 그대로 적용하지 않습니다.
첫 성공 기준은 코드를 실행한 터미널의 출력 창에 라벨 목록이 나오고, 연결하려던 계정의 라벨과 맞는 것입니다. 이 예제의 결과는 메일 본문 요약이 아닙니다. 먼저 인증과 조회를 확인한 뒤 원하는 메시지를 읽는 단계로 확장합니다.
예제의 credentials.json은 앱 인증 설정이고, 실행 중 만들어지는 token.json은 사용자 접근 토큰을 저장합니다. 토큰은 앱이 허용된 권한으로 접근할 때 쓰는 값입니다. 두 파일을 공개 저장소나 질문에 붙이지 말고, 오류를 질문할 때는 비밀값을 지운 메시지만 전달합니다.
막혔을 때 확인할 순서
| 관찰한 결과 | 먼저 확인할 내용 |
|---|---|
| 로그인 또는 동의 단계에서 막힘 | 선택 계정, 앱 대상과 테스트 사용자, 조직 관리자 정책 |
| 인증 정보 파일을 찾지 못함 | 작업 폴더와 공식 예제의 파일 이름 |
| 라벨은 나오는데 메일 본문은 없음 | 실행한 것이 라벨 조회 예제인지 |
| 검색 결과가 0건 | 계정과 검색 조건을 좁혀 실제로 맞는 메일이 있는지 |
| 상세 조회를 찾지 못함 | 메시지 ID와 대화 ID를 혼동했는지 |
| 권한 부족 오류 | 요청 메서드에 필요한 스코프와 실제 동의 범위 |
| 변경 알림이 끊김 | 구독 갱신, 만료 시각과 이력 동기화 상태 |
처음부터 권한을 전부 추가해서 오류를 없애려 하지 않습니다. 어떤 요청에서 어떤 오류가 났는지 먼저 기록합니다. 인증 이후에도 페이지 처리, 중복 실행과 누락 복구를 시험해야 하므로 로그인 성공만으로 자동화가 완성됐다고 판단하지 않습니다.
다음 연습은 직접 고른 업무 하나를 조회할 자료 → 처리 → 검수 → 필요한 행동 네 단계로 적는 것입니다. 자동 발송이 없는 읽기 도구부터 완성하고, 원문과 결과가 맞는지 확인하는 습관을 먼저 익힙니다.
3줄 요약
-
Gmail API는 프로그램이 허용된 범위에서 메일을 조회하고 정리하거나 초안을 만들고 발송하도록 연결하는 기능입니다.
-
목록 조회는 메시지 ID를 찾는 단계이며 본문 조회, AI 처리와 발송은 각각 별도 작업입니다.
-
처음에는 가상 응답과 읽기 예제로 결과를 확인하고 수정 및 발송 기능은 필요한 권한과 검수 절차를 정한 뒤 추가합니다.
제대로 이해했는지 한 문제로 확인해 볼까요?
답을 고르면 바로 풀이가 나와요.
messages.list 응답에 id와 threadId만 있습니다. 본문이 필요하면 다음에 무엇을 하나요?
이 글이 도움이 되었나요?
메일, 회의록, 리포트처럼 반복되는 일을 AI로 자동화하는 순서와 안전장치를 다룹니다
코스 전체 보기 →
새 글과 AI 소식을 메일로 받아 보세요
AI가 바꾸는 일과 도구, 측정 실무 이야기를 매주 한 번 보내 드려요.