Guide

Gmail API: 스팸·휴지통 메시지 조회

스크립트가 사서함의 모든 메시지를 나열하는데, 찾고 있던 피싱 샘플만 나타나지 않습니다. 코드의 버그가 아닙니다. Gmail API는 명시적으로 요청하지 않는 한 messages.list 결과에서 SPAM과 TRASH를 제외합니다. 이 가이드는 스팸과 휴지통을 읽는 문서화된 세 가지 방법 — includeSpamTrash 파라미터, labelIds 필터, in:spam 검색 쿼리 — 과 플래그 하나로 끝나는 CLI 대안을 다룹니다.

Written by Aaron de Mello Senior Engineering Manager

Verified — CLI 3.1.16 · Gmail · last tested June 6, 2026

이 가이드에서 사용하는 명령어 레퍼런스: nylas email list, nylas email folders list.

Gmail API는 왜 스팸과 휴지통 메시지를 반환하지 않나요?

Gmail API는 기본적으로 users.messages.list 응답에서 SPAM과 TRASH 시스템 라벨을 제외합니다. 이 동작은 includeSpamTrash 쿼리 파라미터가 제어하며 기본값은 false입니다. messages.list 레퍼런스에 따르면 true로 설정하면 "include messages from SPAM and TRASH in the results"(결과에 SPAM과 TRASH의 메시지를 포함)합니다.

이 기본값은 받은편지함 스타일 앱에는 합리적이지만, 실제 워크로드 3가지를 망가뜨립니다: 악용·피싱 분석, 사서함 전체 백업, 오탐 복구 스크립트입니다. messages.list 호출 한 번은 할당량 5유닛을 소모하고 기본 100개(maxResults 사용 시 500개)의 메시지 ID를 반환하므로, 해결책은 추가 요청이 아니라 파라미터 하나를 바꾸는 것입니다.

includeSpamTrash로 스팸과 휴지통을 포함하려면?

messages.list에 includeSpamTrash=true를 설정하면 스팸과 휴지통 메시지가 나머지 결과와 함께 반환됩니다. 결과를 필터링하는 게 아니라 결과 집합을 넓히는 옵션이므로, 사서함 전체를 훑어야 할 때 사용하세요. maxResults=500과 조합하면 요청 한 번이 기본 페이지 크기의 5배를 커버합니다.

아래 Python 예제는 google-api-python-client를 사용해 처음 500개 결과 중 SPAM 또는 TRASH 라벨이 붙은 메시지가 몇 개인지 셉니다. 후속 messages.get 호출은 각각 할당량 20유닛, 즉 목록 호출의 4배를 소모한다는 점에 유의하세요.

from googleapiclient.discovery import build

service = build("gmail", "v1", credentials=creds)

# Include spam and trash in a full-mailbox listing
results = service.users().messages().list(
    userId="me",
    includeSpamTrash=True,
    maxResults=500,
).execute()

ids = [m["id"] for m in results.get("messages", [])]
print(f"{len(ids)} messages, spam and trash included")

# Check which labels a specific message carries
msg = service.users().messages().get(
    userId="me", id=ids[0], format="minimal"
).execute()
print(msg["labelIds"])  # e.g. ['SPAM'] or ['TRASH']

이 파라미터가 없으면 같은 호출이 SPAM 또는 TRASH 라벨이 붙은 메시지를 조용히 누락시킵니다. 경고도 없고 몇 개가 제외됐는지도 알려주지 않습니다. 이 플래그를 빠뜨린 백업 스크립트가 사서함 크기를 적게 보고하고 복구 가능한 메일을 놓치는 이유입니다.

labelIds로 스팸 메시지만 나열하려면?

messages.list에 labelIds=["SPAM"]을 전달하면 includeSpamTrash 없이도 스팸 메시지만 반환됩니다. API 레퍼런스에 따르면 이 필터는 "with labels that match all of the specified label IDs"(지정한 라벨 ID를 모두 가진) 메시지를 반환하므로, 라벨 ID 하나만 넘기면 정확히 그 폴더를 얻습니다. 삭제된 메일은 같은 방식으로 ["TRASH"]를 사용하세요.

세 번째 방법은 q 파라미터입니다. 같은 레퍼런스에 따르면 이 파라미터는 "supports the same query format as the Gmail search box"(Gmail 검색창과 동일한 쿼리 형식을 지원)합니다. 따라서 q="in:spam"은 labelIds 필터와 동등하며, from:이나 after: 같은 다른 연산자와 한 문자열에서 조합할 수 있습니다.

# Spam only, via labelIds
spam = service.users().messages().list(
    userId="me", labelIds=["SPAM"], maxResults=100
).execute()

# Trash only
trash = service.users().messages().list(
    userId="me", labelIds=["TRASH"], maxResults=100
).execute()

# Search-style: spam from one sender in the last week
recent = service.users().messages().list(
    userId="me", q="in:spam from:billing@suspicious.example newer_than:7d"
).execute()

의도에 따라 고르세요: 단일 폴더를 깔끔하게 읽을 때는 labelIds, 스팸 범위에 발신자·날짜·첨부 조건을 결합해야 할 때는 q입니다. 두 방식 모두 목록 호출당 동일하게 할당량 5유닛을 소모합니다. SPAM과 TRASH는 Gmail의 13개 기본 시스템 라벨 중 2개로, Gmail 라벨 가이드에 정리되어 있습니다.

Gmail은 휴지통 메시지를 얼마나 보관하나요?

Gmail은 삭제된 메시지를 최대 30일간 휴지통에 보관합니다. Google의 복구 문서에 따르면, "Up to 30 days after deletion: You can find the message in Trash"(삭제 후 30일까지는 휴지통에서 메시지를 찾을 수 있음)이며 30일이 지나면 "The message is permanently deleted."(메시지가 영구 삭제됨)입니다. TRASH 라벨을 대상으로 만드는 모든 복구 스크립트는 이 시계와 경주하는 셈입니다.

이 기간이 자동화 스케줄을 결정합니다. 휴지통을 JSON으로 내보내는 주간 cron 작업은 Gmail이 메시지를 삭제하기 전에 4번의 기회가 있지만, 월간 작업은 메시지를 통째로 놓칠 수 있습니다. 스팸 분류도 실무 패턴은 같습니다: 팀의 사고 대응 주기보다 짧은 일정으로 SPAM 라벨을 나열하고, 증거로 필요할 수 있는 것은 모두 보존하세요.

CLI에서 스팸과 휴지통을 읽으려면?

nylas email list --folder SPAM 명령은 Google Cloud 프로젝트, OAuth 동의 화면, Python 클라이언트 설정 없이 Gmail 스팸 메시지를 JSON으로 반환합니다. CLI의 --folder 플래그는 모든 Gmail 시스템 라벨 ID를 받으므로 TRASH도 동일하게 동작하고, --all-folders는 한 번의 실행으로 모든 폴더를 훑습니다. 인증은 nylas auth login 한 번이면 됩니다.

# List spam messages
nylas email list --folder SPAM --limit 20

# List trash as JSON for scripting
nylas email list --folder TRASH --json --limit 50

# Sweep every folder, spam and trash included
nylas email list --all-folders --json --limit 200

# Extract sender addresses from spam for a blocklist review
nylas email list --folder SPAM --json --limit 50 | \
  jq -r '.[].from[0].email' | sort | uniq -c | sort -rn

이 명령어들은 CLI 3.1.16에서 실제 Gmail 계정으로 검증했습니다. 같은 --folder 문법이 Outlook과 IMAP 계정에서도 해당 폴더 이름으로 동작하므로, Gmail용으로 작성한 스팸 검토 스크립트가 Gmail API의 라벨 모델을 건드리지 않고 다른 프로바이더로 이식됩니다. 연결된 계정의 정확한 폴더 ID는 nylas email folders list를 실행해 확인하세요.

다음 단계