Guide

Gmail API 검색 쿼리 예제

q 파라미터, 라벨, 카테고리, 날짜, 첨부 파일, rfc822msgid를 다루는 Gmail API 검색 쿼리 예제입니다. 직접 API 구문을 먼저 살펴본 뒤, 자주 쓰는 사례를 지원되는 CLI 필터로 옮기는 방법까지 다룹니다.

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Updated June 6, 2026

Verified — CLI 3.1.11 · last tested May 16, 2026

Gmail API 검색 쿼리 구문은 어떻게 동작하나요?

Gmail API 검색 쿼리 구문은 Gmail 검색 표현식을 users.messages.list의 q 쿼리 파라미터에 전달하는 방식으로 동작합니다. Google 문서에 따르면 이 파라미터는 Gmail 검색창과 동일한 쿼리 형식을 지원하므로, HTTP 요청 하나로 발신자, 수신자, 제목, 읽지 않음 상태, 날짜, 첨부 파일 여부, 메시지 ID를 기준으로 필터링할 수 있습니다.

핵심 제약은 messages.list가 전체 메시지 본문이 아니라 메시지 ID만 반환한다는 점입니다. 이 메서드는 기본 100건을 반환하고 페이지당 최대 500건까지 허용하므로, 1,500건이 매칭되는 검색은 콘텐츠를 가져오기 전에 최소 3번의 list 호출이 필요합니다. 공식 users.messages.list 레퍼런스에는 q를 gmail.metadata 스코프와 함께 사용할 수 없다는 점도 명시되어 있습니다.

다음의 최소 Python 예제는 직접 API 호출의 형태를 보여줍니다. 한 발신자가 보낸 읽지 않은 메일을 검색하고, 첫 페이지를 ID 50개로 제한하며, 메시지 본문 읽기는 두 번째 단계로 남겨둡니다. 본문을 읽을 때마다 API 호출이 추가되기 때문에 이 분리가 중요합니다.

response = service.users().messages().list(
    userId="me",
    q="from:billing@stripe.com is:unread",
    maxResults=50,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

발신자, 수신자, 제목, 읽지 않음 상태로 어떻게 검색하나요?

Gmail 검색 쿼리는 필드 연산자를 문자열 하나에 조합할 수 있으므로 발신자, 수신자, 제목, 읽지 않음 필터를 같은 q 값에 넣을 수 있습니다. 실용적인 패턴은 페이지네이션이 시작되기 전에 쿼리를 좁게 유지하는 것입니다. 결과가 하나 늘어날 때마다 나중에 messages.get 호출이 하나 더 생길 수 있기 때문입니다.

Google의 예제에는 from:, rfc822msgid:, is:unread 같은 연산자가 등장합니다. Gmail UI는 to:, subject:, 정확한 구문 검색, 부정 검색도 지원합니다. API 코드에서 이 연산자들은 URL 인코딩된 문자열일 뿐이며, 서버가 검색을 수행해 매칭되는 메시지 ID를 반환합니다. 에이전트나 cron 작업에는 25건 제한이 좋은 첫 시도입니다. 전체 사서함을 읽지 않고도 충분한 후보를 확보할 수 있기 때문입니다.

다음 CLI 명령은 nylas email search의 검증된 플래그를 사용합니다. 위치 인자 쿼리가 invoice인 이유는 현재 명령이 와일드카드가 아닌 쿼리를 제목 텍스트로 취급하기 때문입니다. from: 같은 필드 연산자는 Gmail API 구문이지 CLI에 그대로 전달되는 것이 아닙니다. 이 명령은 스크립트나 에이전트 도구를 위해 JSON 결과 25건을 반환합니다.

nylas email search "invoice" \
  --from "billing@stripe.com" \
  --unread \
  --limit 25 \
  --json

Gmail 라벨과 카테고리 검색은 어떻게 동작하나요?

Gmail 라벨은 폴더가 아닙니다. 여러 메시지에 붙을 수 있는 태그이며, 메시지 하나가 라벨 여러 개를 동시에 가질 수 있습니다. Google 문서는 2가지 라벨 계열을 정의합니다: INBOX 같은 예약된 SYSTEM 라벨과, 사서함 소유자나 연동 프로그램이 만든 커스텀 USER 라벨입니다.

Gmail 라벨 가이드는 INBOX, SPAM, TRASH, UNREAD, STARRED를 포함한 주요 시스템 라벨과 CATEGORY_PERSONAL, CATEGORY_SOCIAL, CATEGORY_PROMOTIONS, CATEGORY_UPDATES, CATEGORY_FORUMS 등 5개의 카테고리 라벨을 나열합니다. 검색 쿼리에서는 category:promotions 같은 사용자용 구문을 쓰는 경우가 많고, API 라벨 필터는 CATEGORY_PROMOTIONS 같은 라벨 ID를 사용합니다.

CLI는 다른 프로바이더에서 사용하는 것과 같은 폴더 스타일 인터페이스로 Gmail 카테고리 라벨을 노출합니다. 다음 예제는 프로모션 메시지 25건을 검색한 뒤, 소셜 메시지를 대상으로 제목 검색을 실행합니다. 두 명령 모두 nylas email search의 검증된 폴더 필터인 --in을 사용합니다.

nylas email search "*" --in "CATEGORY_PROMOTIONS" --limit 25 --json

nylas email search "webinar" \
  --in "CATEGORY_SOCIAL" \
  --limit 25 \
  --json

MIME 디코딩 없이 첨부 파일을 어떻게 검색하나요?

Gmail 첨부 파일 검색은 MIME 파싱이 아니라 검색 인덱스에서 시작해야 합니다. has:attachment 쿼리는 코드가 메시지 페이로드를 다운로드하기 전에 결과 집합을 좁혀주므로, 파일이 있는 메시지가 3건뿐이라는 사실을 알아내려고 큰 받은편지함의 모든 메시지를 디코딩하는 일을 피할 수 있습니다.

첨부 파일 다운로드는 여전히 두 번째 API 단계입니다. Gmail 첨부 파일 리소스는 attachmentId를 별도의 messages.attachments.get 요청에 사용하는 값으로 설명하며, 반환되는 데이터는 base64url로 인코딩되어 있습니다. 즉 직접 Gmail 연동에는 검색, 메시지 파트 순회, 첨부 파일 ID 조회, 바이트 디코딩, 파일 쓰기가 모두 필요합니다.

CLI는 첫 단계를 작게 유지하고, 메시지와 첨부 파일 ID를 선택할 때까지 파일 다운로드를 미룹니다. 다음 3개 명령은 첨부 파일이 있는 메시지를 검색하고, 선택한 메시지 하나의 첨부 파일 목록을 확인한 뒤, 특정 첨부 파일을 로컬 경로로 다운로드합니다.

nylas email search "*" --has-attachment --from "billing@stripe.com" --limit 25 --json

nylas email attachments list <message-id> --json

nylas email attachments download <attachment-id> <message-id> --output ./invoice.pdf

날짜 범위와 오래된 메일은 어떻게 검색하나요?

Gmail 날짜 검색은 검색 표현식 안에서 after:, before:, older:, newer: 같은 연산자를 사용하고, CLI는 날짜 경계를 명시적인 플래그로 노출합니다. 자동화에서는 두 방식 모두 고정 날짜를 사용해야 같은 작업을 24시간 주기로 재실행해도 반복 가능한 결과가 나옵니다.

고정된 기간은 숨겨진 사서함 스캔을 방지합니다. 월간 인보이스 작업이라면 2026년 1월만 검색한 뒤, 제목과 발신자를 기준으로 순위를 매기고 선택한 메시지만 읽으면 됩니다. API 코드에서는 그 날짜 범위가 q 문자열 안에 들어갑니다. CLI에서는 --after와 --before가 날짜 경계를 리뷰어에게 그대로 보여주고 래퍼에서 강제하기도 쉽습니다.

다음 명령은 2026년 1월 1일부터 2월 1일 사이의 인보이스 제목 메시지를 검색합니다. 최대 50건의 후보를 반환하는데, 검색 단계가 수천 건의 본문 읽기로 불어나지 않으면서도 사람용 보고서나 에이전트 순위 매기기에 충분한 양입니다.

nylas email search "invoice" \
  --after 2026-01-01 \
  --before 2026-02-01 \
  --limit 50 \
  --json

rfc822msgid로 특정 메시지 하나를 어떻게 찾나요?

rfc822msgid: 연산자는 특정 인터넷 메시지 ID 하나를 검색합니다. 웹훅, 반송 메일, 로그 라인, 지원 티켓에 원본 Message-ID 헤더가 기록되어 있을 때 유용합니다. 제목으로 스캔하는 대신, 보통 1개의 대화에 매핑되는 전역적으로 의미 있는 식별자를 직접 겨냥하는 방식입니다.

Google은 users.messages.list 문서 예제에 rfc822msgid:를 포함하고 있습니다. 이 연산자는 모호한 텍스트 검색을 우회하기 때문에 중복 전송, 웹훅 팬아웃, 답장 스레딩을 디버깅할 때 가장 유용합니다. 라벨이나 스레드 뷰에 사본이 존재하면 결과에 메시지가 1건 이상 포함될 수 있으므로, 낮은 limit을 유지하고 본문을 읽기 전에 ID를 확인하세요.

CLI는 현재 rfc822msgid:를 위한 raw Gmail q 패스스루를 제공하지 않습니다. 이 연산자가 정확히 필요하다면 직접 Gmail API를 사용하고, 발신자, 제목, 날짜, 폴더, 첨부 파일 필터로 조회를 근사할 수 있을 때만 CLI 플래그를 사용하세요. 다음 예제는 API 결과 집합을 ID 5건으로 제한합니다.

response = service.users().messages().list(
    userId="me",
    q="rfc822msgid:<20260516.12345@example.com>",
    maxResults=5,
).execute()

message_ids = [message["id"] for message in response.get("messages", [])]

Gmail 검색 결과를 어떻게 안전하게 페이지네이션하나요?

안전한 Gmail 검색 페이지네이션은 쿼리를 고정하고, 현재 nextPageToken을 저장하며, 비즈니스 한도에 도달하는 즉시 중단합니다. API는 페이지당 최대 500건을 허용하지만, 프로덕션 작업이라면 보통 200건이나 1,000건처럼 더 작은 전체 상한을 정의해야 합니다.

페이지네이션은 직접 API 코드가 빠르게 불어나는 지점입니다. nextPageToken을 위한 루프, 결과 상한, 일시적 장애에 대한 재시도 동작, 같은 페이지를 두 번 처리하지 않고 재개하는 방법이 모두 필요합니다. 일간 작업에 최신 영수증 200건만 필요하다면, 2,000건을 가져오는 것은 결과 품질을 높이지 못한 채 할당량 비용과 검토 시간만 늘립니다.

다음 Python 루프는 검색 쿼리를 고정하고 메시지 ID 200건 이후 중단합니다. 직접 연동이 제목, 스니펫, 본문을 위해 messages.get을 호출하기도 전에 떠안아야 하는 추가 상태를 보여줍니다.

query = "from:billing@stripe.com has:attachment after:2026/01/01"
page_token = None
message_ids = []

while len(message_ids) < 200:
    response = service.users().messages().list(
        userId="me",
        q=query,
        maxResults=min(100, 200 - len(message_ids)),
        pageToken=page_token,
    ).execute()

    message_ids.extend(message["id"] for message in response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

Gmail 검색 결과를 어떻게 읽을 수 있는 메시지로 바꾸나요?

messages.list는 경량 메시지 레코드를 반환하기 때문에, Gmail 검색 결과는 두 번째 가져오기 단계를 거쳐야 읽을 수 있게 됩니다. 제목, 발신자, 스니펫, 본문을 보여주려면 코드가 선택한 ID에 대해 messages.get을 호출한 뒤 헤더와 base64url로 인코딩된 페이로드 데이터를 파싱해야 합니다.

많은 예제가 숨기는 부분이 바로 여기입니다. 메시지 ID 50건을 반환하는 검색은 워크플로가 모든 매칭을 읽는다면 후속 호출 50건으로 변할 수 있습니다. 에이전트 워크플로에서는 먼저 검색하고, 메타데이터로 순위를 매긴 뒤, 선택한 메시지 1~5건만 읽고 중단하는 패턴이 더 안전합니다. CLI는 그 검색 경계를 별도의 nylas email search와 nylas email read 명령으로 그대로 반영합니다.

다음 명령은 먼저 검색하고, 그다음 선택한 메시지 하나를 읽습니다. 이 2단계 구조는 의도된 것입니다. 스크립트나 모델이 본문 콘텐츠에 호출을 더 쓰기 전에 ID와 스니펫을 검토할 수 있게 해줍니다.

nylas email search "contract" --from legal@example.com --limit 10 --json

nylas email read <message-id> --json

CLI는 프로바이더 간 검색을 어떻게 매핑하나요?

6개 프로바이더 계열이 각자의 검색 엔진과 사서함 모델을 유지하는 동안, CLI는 개발자에게 검색 명령 하나를 제공합니다. Gmail에는 q와 라벨이 있고, Microsoft 메일에는 Graph 필터링과 폴더 API가 있으며, IMAP 서버는 SEARCH와 사서함 폴더를 노출합니다. 유용한 계약은 프로바이더별 동작을 뒤에 숨긴 하나의 명령 표면입니다.

이 가이드의 프로바이더 측 동작은 모든 백엔드에서 실제 엔드투엔드 테스트를 거친 것이 아니라 Google 문서와 검증된 CLI 도움말을 기준으로 기술했습니다. category:promotions와 rfc822msgid: 같은 Gmail 전용 연산자는 여기서 직접 API 구문입니다. 프로바이더 간 워크플로에는 --from, --to, --subject, --after, --before, --has-attachment 같은 CLI 플래그를 사용하세요.

필요한 작업	Gmail API 형태	CLI 형태
발신자 검색	`q="from:alice@example.com"`	`nylas email search "*" --from alice@example.com`
읽지 않음 검색	`q="is:unread"`	`nylas email search "*" --unread`
첨부 파일 검색	`q="has:attachment"`	`nylas email search "*" --has-attachment`
날짜 범위	`q="invoice after:2026/01/01 before:2026/02/01"`	`nylas email search "invoice" --after 2026-01-01 --before 2026-02-01`

라벨, 폴더, 카테고리는 검색 품질에 어떤 영향을 주나요?

Gmail 검색 품질은 라벨, 폴더, 카테고리 중 올바른 사서함 개념을 고르는 데 달려 있습니다. Gmail 라벨은 다대다 태그이고, 프로바이더 폴더는 보통 하나의 위치이며, Gmail 카테고리는 Google이 할당하는 시스템 라벨입니다. 이 3가지 사서함 개념을 섞어 쓰는 것이 검색 결과가 너무 많거나 기대한 메시지를 놓치는 흔한 원인입니다.

사용자가 메시지 속 단어를 기억할 때는 전문 검색을 사용하세요. 워크플로가 이미 메시지를 분류해 두었다면 라벨을 사용하세요. 프로모션이나 소셜 같은 Gmail 탭이 대상이라면 카테고리를 사용하세요. Outlook, Exchange, Yahoo, iCloud, IMAP에도 잘 매핑되는 프로바이더 중립적인 명령이 필요하다면 폴더를 사용하세요.

보통은 2단계 패턴이 디버깅하기 가장 쉽습니다. 사용 가능한 폴더나 라벨을 먼저 나열한 뒤, 선택한 위치 안에서 검색하세요. 그러면 폴더 이름이 로그에 그대로 남고, 프로바이더 간 워크플로가 CLI의 폴더 추상화를 써야 할 자리에 Gmail 전용 라벨을 하드코딩하는 일을 피할 수 있습니다.

작업을 배포하기 전에 Gmail 검색 쿼리를 어떻게 테스트하나요?

Gmail 검색 쿼리를 cron, CI, 에이전트 도구에 넣기 전에 4단계 점검 루프로 테스트하세요: 작은 limit으로 실행하고, ID를 검토하고, 선택한 메시지 1건을 읽고, 정확한 쿼리 문자열을 저장합니다. 이 과정은 수백 건의 메시지 본문을 읽기 전에 지나치게 넓은 검색을 걸러냅니다.

첫 실행에는 프로덕션 상한이 아니라 --limit 5나 --limit 10을 사용해야 합니다. 최신 매칭 5건이 기대한 종류의 메일인지 확인한 뒤, 발신자, 날짜, 폴더, 첨부 파일 필터가 올바르게 동작할 때만 limit을 넓히세요. 월간 작업이라면 최소 2개의 날짜 범위를 테스트하세요: 매칭이 확실히 있는 범위 하나와 비어 있는 범위 하나입니다.

다음 스모크 테스트는 출력을 작고 검토하기 쉽게 유지합니다. 첫 번째 명령은 검색 범위가 좁혀졌음을 증명하고, 두 번째 명령은 후보 하나를 읽습니다. 선택한 메시지가 잘못됐다면 페이지네이션이나 전송 로직을 추가하기 전에 쿼리를 고치세요.

nylas email search "invoice" --from billing@example.com --limit 5 --json

nylas email read <message-id> --json

AI 에이전트는 Gmail 검색을 어떻게 안전하게 사용해야 하나요?

AI 에이전트는 Gmail 검색을 전체 사서함을 읽어도 된다는 허가가 아니라 경계가 있는 검색 단계로 사용해야 합니다. 안전한 에이전트 루프는 좁게 검색하고, 후보를 제한하고, 메타데이터를 검토하고, 선택한 메시지만 읽으며, 전송이나 파괴적 작업 전에는 승인을 요청합니다.

그 차이는 측정 가능합니다. 메시지 25건을 검색해 본문 3건을 읽는 에이전트는 본문 250건을 먼저 읽는 에이전트보다 프롬프트, 비용, 프라이버시 발자국이 훨씬 작습니다. 검색 쿼리는 감사 산출물도 됩니다. 리뷰어가 에이전트의 검색이 from:customer@example.com이었는지, has:attachment였는지, 아니면 contract 같은 광범위한 용어였는지 확인할 수 있습니다.

다음 셸 패턴은 에이전트 도구의 좋은 기준선입니다. 후보 ID 25건을 수집하고, 순위 매기기 단계가 하나를 고르게 한 뒤, 그제야 본문 콘텐츠를 읽습니다. 명령 이름이 감사 로그와 명령 허용 목록에 깔끔하게 연결됩니다.

nylas email search "contract" --from customer@example.com --limit 25 --json \
  | jq -r '.[].id' \
  | head -5

nylas email read <selected-message-id> --json

CLI 대신 Gmail API를 언제 사용해야 하나요?

애플리케이션에 Gmail 전용 제어 영역 1가지가 필요할 때 Gmail API를 직접 사용하세요: rfc822msgid: 같은 raw q 연산자, Gmail 관리 기능, 자체 Google Cloud 소유권, 도메인 전체 위임, Pub/Sub watch 갱신, 또는 이미 Google OAuth 플로를 내장한 UI 등입니다. 터미널 워크플로, 에이전트 도구, cron 작업, 움직이는 부품이 적은 멀티 프로바이더 스크립트가 필요할 때는 CLI를 사용하세요.

이 결정은 Gmail API의 좋고 나쁨이 아니라 배관을 누가 소유할지의 문제입니다. 직접 API 코드는 OAuth 설정, 쿼리 작성, 페이지네이션, 메시지 읽기, base64url 디코딩, 재시도 동작, 프로바이더 종속까지 모두 소유합니다. CLI 경로는 명령 선택과 출력 처리만 소유하고, 프로바이더 연동은 Nylas가 뒤에서 처리합니다.

대부분의 개발자 자동화는 CLI 경로로 시작하고, Gmail 전용 기능을 구체적으로 댈 수 있을 때만 직접 Gmail API 호출로 옮기세요. 이 규칙은 일회성 스크립트, AI 에이전트 도구, CI 작업이 수명이 긴 OAuth 클라이언트로 변하는 것을 막아줍니다.

다음에는 무엇을 만들면 좋을까요?

Gmail API 페이지네이션과 동기화 -- nextPageToken, historyId, 라벨 범위 지정, 검색 결과 페이지네이션
Gmail API 스팸·휴지통 메시지 -- includeSpamTrash, labelIds=["SPAM"], in:spam 쿼리
Gmail API 카테고리 라벨 -- category: 연산자와 labelIds AND 필터 함정
터미널에서 Gmail 이메일 목록 보기 -- 목록, 검색, 읽기, 라벨, JSON 출력을 위한 Gmail CLI 예제
2026년 Gmail API 할당량 -- 메서드별 비용, 경계가 있는 검색 루프, 더 안전한 에이전트 패턴
AI 에이전트를 위한 Gmail API 제약 -- OAuth, MIME 파싱, 할당량, 도구 설계 리스크
AI 에이전트용 이메일 API 비교 -- Gmail API, Graph, IMAP, MCP, CLI 도구 중에서 선택하기
이메일 검색 명령어 -- 발신자, 날짜, 첨부 파일, 폴더, limit, JSON 출력을 위한 정확한 플래그
이메일 읽기 명령어 -- 경계가 있는 검색 후 선택한 메시지 1건 읽기
전체 명령어 레퍼런스 -- 모든 이메일, 캘린더, 연락처, 웹훅, MCP, 감사 명령어
Gmail API 검색·필터 가이드 -- messages.list, threads.list, 검색 쿼리를 다루는 Google의 프로바이더 네이티브 가이드