Gmail API 페이지네이션과 동기화 완전 정리

Gmail API의 nextPageToken과 maxResults는 어떻게 동작하나요?

Gmail API의 maxResults 파라미터는 users.messages.list가 한 페이지에 반환하는 메시지 ID 개수를 제어하며, 최대 500까지 지정할 수 있습니다. 일치하는 메시지가 더 있으면 응답에 nextPageToken이 포함됩니다. 응답에 토큰이 더 이상 포함되지 않을 때까지, 그 토큰을 다음 요청의 pageToken으로 다시 전달합니다.

자주 검색되는 gmail api nextPageToken maxResults에 대한 핵심 규칙은, maxResults가 전체 결과 한도가 아니라 페이지 크기일 뿐이라는 점입니다. 일치하는 메시지가 10,000개인 사서함이라면 여전히 반복 요청, 토큰 보존, 재시도 처리, 그리고 메시지 본문마다 별도의 messages.get 호출이 필요합니다.

Gmail API 페이지네이션의 동작 방식

Gmail API 페이지네이션은 큰 결과 집합을 여러 HTTP 응답으로 나누며, 각 응답에는 호출자가 다음 배치를 가져오기 위해 다시 전달해야 하는 nextPageToken이 들어 있습니다. messages.list 엔드포인트는 요청당 최대 500개의 결과를 반환하므로, 메시지가 10,000개인 받은편지함을 끝까지 순회하려면 최소 20번의 순차 API 호출이 필요합니다.

Gmail API messages.list 문서에 따르면, 호출당 비용은 할당량 5단위이고 기본 페이지 크기는 100입니다(maxResults로 최대 500까지 설정 가능). 모든 요청에는 유효한 OAuth2 액세스 토큰이 필요합니다. 아래 루프는 이 패턴을 Python으로 보여줍니다 — messages.list를 반복 호출해 메시지 ID를 모으고, nextPageToken이 없으면 중단합니다:

from googleapiclient.discovery import build

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

all_messages = []
page_token = None

while True:
    response = service.users().messages().list(
        userId="me",
        maxResults=500,
        pageToken=page_token,
    ).execute()

    all_messages.extend(response.get("messages", []))
    page_token = response.get("nextPageToken")

    if not page_token:
        break

print(f"Fetched {len(all_messages)} message IDs")

메시지 ID를 모으는 데만 18줄입니다. 제목, 발신자, 본문을 가져오려면 여전히 각 ID에 대해 messages.get을 호출해야 하고, 현행 Gmail 할당량 표 기준으로 호출마다 할당량 20단위가 추가로 듭니다.

Gmail 증분 동기화의 동작 방식

Gmail 증분 동기화는 단조 증가하는 historyId로 사서함 변경 사항을 추적하므로, 마지막 동기화 이후 바뀐 것만 가져올 수 있습니다. 메시지 10,000개짜리 받은편지함을 전체 재페이지네이션하면 messages.list 호출만으로 최소 할당량 100단위가 들기 때문에, 그 오버헤드를 피하기 위해 신규·삭제·라벨 변경 메시지만 반환하는 history.list 엔드포인트가 존재합니다.

마지막 동기화의 historyId를 저장해 둡니다. 다음 실행 때 startHistoryId와 함께 history.list를 호출하면 그 이후의 변경 사항만 받습니다. Gmail 동기화 가이드는 로컬 복사본을 동기화 상태로 유지하는 기본 접근법으로 이 방식을 권장합니다. historyTypes 파라미터로 변경 유형을 필터링할 수 있습니다: messageAdded, messageDeleted, labelAdded, labelRemoved. history.list 호출당 비용은 할당량 2단위로, 5단위인 messages.list 호출보다 60% 저렴합니다. 아래 Python 함수는 페이지네이션된 히스토리 레코드를 순회하며 변경 사항을 모으고, 다음 동기화에 쓸 최신 historyId를 반환합니다:

def get_changes_since(service, start_history_id):
    """Fetch all mailbox changes since the given historyId."""
    changes = []
    page_token = None

    while True:
        response = service.users().history().list(
            userId="me",
            startHistoryId=start_history_id,
            historyTypes=["messageAdded", "messageDeleted"],
            pageToken=page_token,
        ).execute()

        changes.extend(response.get("history", []))
        page_token = response.get("nextPageToken")

        if not page_token:
            break

    new_history_id = response.get("historyId")
    return changes, new_history_id

함정이 하나 있습니다: 히스토리 ID는 대략 30일이 지나면 만료됩니다. 저장해 둔 historyId가 너무 오래되면 history.list가 404 Not Found(때로는 410 Gone)를 반환하고, 전체 동기화로 폴백해야 합니다. 코드가 두 경로를 모두 처리해야 합니다.

직접 구현할 때의 문제점

프로덕션급 Gmail 동기화 클라이언트를 만든다는 것은 OAuth2 토큰 수명 주기, 만료된 히스토리 폴백, 레이트 리밋, 부분 실패를 모두 직접 유지보수하는 코드로 처리한다는 뜻입니다. 20줄짜리 페이지네이션 루프로 시작한 코드는 토큰 갱신 콜백, 429 응답에 대한 지수 백오프, 델타 동기화와 전체 동기화의 이중 코드 경로를 더하고 나면 80-120줄로 불어납니다. 엣지 케이스는 계속 쌓입니다:

• OAuth2 토큰 관리 — Gmail 액세스 토큰은 3,600초마다 만료됩니다. 동기화 루프는 만료된 토큰을 감지하고, 리프레시 토큰으로 갱신하고, 실패한 요청을 재시도해야 합니다. 토큰 갱신 콜백, 오류 처리, 재시도 로직이 필요하다는 뜻입니다.
• 만료된 historyId 폴백 — history.list가 404를 반환하면 델타 동기화를 버리고 전체 페이지네이션 동기화를 대신 실행해야 합니다. 두 코드 경로 모두 올바르게 동작해야 합니다.
• 레이트 리밋 — 신규 Gmail API 프로젝트는 프로젝트별·사용자별 분당 할당량 6,000단위를 받습니다. messages.list 호출은 5단위, messages.get은 20단위, history.list는 2단위입니다. 큰 사서함을 동기화한다면 클라이언트 측 스로틀링과 429 Too Many Requests에 대한 지수 백오프가 필요합니다.
• 부분 페이지 실패 — 페이지네이션 도중 네트워크 오류가 나면 결과의 절반만 남습니다. 처음부터 재시도할까요, 마지막 페이지 토큰부터 할까요? 상태 추적이 필요합니다.
• Gmail API 설정 오버헤드 — Gmail API를 호출하는 코드를 한 줄이라도 쓰기 전에 Google Cloud 프로젝트, OAuth 동의 화면, 클라이언트 ID와 시크릿, 그리고 console.cloud.google.com에 설정한 리디렉션 URI가 필요합니다. 웹 폼을 클릭하며 15-20분을 보내야 합니다.

다섯 가지 문제를 모두 다루는 신뢰할 만한 동기화 루프는 로깅, 영속화, 다중 계정 지원을 추가하기도 전에 Python 80-120줄이 됩니다.

관련 API 페이지네이션 및 이메일 워크플로 가이드

Gmail 페이지네이션은 보통 인접한 통합 작업과 함께 등장합니다: Calendar 이벤트 동기화, 프로바이더 중립적인 받은편지함 목록 조회, 웹훅 전달, API 할당량 계획, 에이전트에 안전한 이메일 액세스. 더 구체적인 구현 경로가 필요할 때 이 지도를 사용하세요.

명령어 하나로 Gmail 이메일 목록 보기

Nylas CLI는 페이지네이션과 동기화 스택 전체를 터미널 명령어 하나로 대체하며, OAuth2 토큰 갱신, 레이트 리밋, 다중 페이지 가져오기를 내부에서 처리합니다. Gmail API 방식이 Python 80-120줄과 Google Cloud에서의 15-20분짜리 Gmail API 설정을 요구하는 반면, CLI는 그것을 한 줄과 2분짜리 설치로 줄입니다.

아래 세 가지 명령어는 흔한 패턴을 보여줍니다: 최근 메시지 목록, 제목 필터, 발신자 필터. 각각은 내부적으로 단일 API 호출처럼 실행되고, CLI가 프로바이더 응답 사이의 페이지네이션을 관리합니다:

# List the 50 most recent emails
nylas email list --limit 50 --json

# Filter by subject
nylas email search "invoice" --json

# Filter by sender
nylas email list --from "boss@company.com" --json

CLI는 보이지 않는 곳에서 Gmail API의 페이지를 순회하고, 만료된 OAuth2 토큰을 자동으로 갱신하고, 결과를 JSON으로 반환합니다. 등록할 Gmail API 프로젝트도, 동의 화면도, 리디렉션 URI도 없습니다. CLI가 처음이라면 시작하기 가이드에서 설치와 최초 인증을 다룹니다.

검색과 필터

Nylas CLI는 messages.list가 사용하는 것과 같은 Gmail q 파라미터에 매핑되는 전문(full-text) 검색과 필드 단위 필터를 지원하지만, 페이지네이션 루프나 OAuth2 배관 작업은 필요 없습니다. Gmail API에서는 검색, 페이지네이션, 메시지 본문 가져오기에 최소 3번의 순차 API 호출이 필요합니다 — CLI는 그것을 명령어 하나로 압축합니다.

아래 세 예제는 가장 흔한 검색 패턴을 다룹니다: 키워드 검색, 읽지 않은 메일 필터, 날짜 범위 필터. 날짜 필터는 nylas email search의 --after와 --before로 제공되며, YYYY-MM-DD 형식 날짜를 받고 모든 메시지에 일치하는 쿼리로 "*"를 허용합니다. 각 예제는 제목, 발신자, 본문을 포함한 전체 메시지 JSON을 반환합니다:

# Full-text search
nylas email search "quarterly report" --json

# Unread emails only
nylas email list --unread --json

# Emails received in the last 7 days
nylas email search "*" --after 2026-06-02 --json

Gmail API로 같은 일을 하려면 쿼리 문자열을 만들고, messages.list에 전달하고, nextPageToken으로 결과를 순회하고, 반환된 각 메시지 ID에 대해 messages.get을 호출해 제목과 본문을 가져와야 합니다. 4단계에 페이지당 최소 할당량 10단위입니다.

ID가 아니라 메시지 내용 읽기

Gmail API의 messages.list 엔드포인트는 메시지 ID만 반환합니다 — 제목, 발신자, 본문은 절대 주지 않습니다. 실제 내용을 읽으려면 수집한 모든 ID에 대해 messages.get을 호출해야 하고, 호출마다 할당량 20단위가 추가로 듭니다. 메시지 10,000개를 순회한 뒤에는 API 호출 10,000번이 더 필요하고, 총 할당량 200,000단위는 2026년 사용자별 프로젝트 한도 기준으로 33사용자-분이 넘는 할당량을 소비합니다.

CLI는 두 단계를 명령어 하나로 합칩니다. nylas email read <id>는 호출 한 번으로 전체 본문이 포함된 메시지 하나를 가져옵니다. nylas email search는 서버 측 쿼리를 수행하고 일치하는 메시지를 내용과 함께 같은 응답으로 반환합니다. 두 명령 모두 전역 --format 플래그를 통해 세 가지 출력 모드를 지원합니다 — table, json, yaml — 그리고 --json은 JSON 모드의 축약형입니다. messages.get이 format=raw로 반환하는 원시 RFC822 소스가 필요하면 nylas email read에 --mime을 전달하세요. JSON 출력은 후속 셸 처리를 위해 jq로 깔끔하게 파이프됩니다.

# Read a single message
nylas email read 18b9a3f2cd47e102 --json

# Search and return full bodies in one round-trip
nylas email search "urgent" --from boss@example.com --json

메시지 대신 스레드 페이지네이션

Gmail은 메시지를 대화 스레드로 묶으며, threads.list 엔드포인트는 messages.list와 별개의 페이지네이션 리소스입니다. 메시지 10,000개짜리 받은편지함은 대화 밀도에 따라 보통 2,000-4,000개의 스레드로 정리되므로, 스레드 목록을 사용하면 총 페이지 수가 60-80% 줄어듭니다. 각 스레드 응답은 messages.list와 같은 nextPageToken 계약을 따르고, 대화의 모든 메시지를 담은 threads[].messages[] 배열을 추가로 제공합니다.

CLI의 스레드 인터페이스는 메시지 인터페이스를 다섯 가지 명령으로 그대로 반영합니다. nylas email threads list는 스레드를 페이지 단위로 순회합니다. nylas email threads show는 ID로 스레드 하나를 가져옵니다. nylas email threads search는 Gmail 스타일 쿼리 문자열을 받습니다. nylas email threads mark는 스레드의 모든 메시지 읽음 상태를 한 번에 변경합니다. nylas email threads delete는 대화 전체를 삭제합니다.

# Paginate threads in pages of 50
nylas email threads list --limit 50 --json

# Mark a whole conversation as read in one command
nylas email threads mark <thread-id> --read

특정 라벨이나 폴더 안에서 페이지네이션하기

Gmail은 메시지를 라벨로 정리합니다 — INBOX, SENT, STARRED, UNREAD, SPAM, TRASH 같은 시스템 라벨과 사용자가 만든 라벨이 있습니다. Microsoft Graph와 IMAP 프로바이더는 대신 폴더를 사용합니다. Gmail messages.list 엔드포인트는 시스템 라벨용 labelIds 배열, 또는 커스텀 라벨용으로 label:Receipts 같은 검색 문법을 쓰는 q 파라미터를 받습니다. 페이지네이션 토큰이 필터 범위를 함께 가지고 다니므로, 라벨 하나로 범위를 좁힌 50,000개짜리 보관함은 그만큼 적은 페이지를 반환합니다.

nylas email search는 쿼리를 라벨 또는 폴더 하나로 한정하는 --in을 받습니다 — 그 안의 모든 메시지에 일치시키려면 쿼리로 "*"를 전달하세요. nylas email folders list는 연결된 계정의 모든 라벨 또는 폴더를 반환하므로, 같은 플래그가 문법 변경 없이 Gmail 라벨, Outlook 폴더, IMAP 폴더 이름에 모두 적용됩니다. 검색 명령의 플래그에는 --unread, --starred, --has-attachment도 포함됩니다.

# List every label or folder on the connected account
nylas email folders list --json

# Paginate only inside the Receipts label
nylas email search "*" --in Receipts --limit 100 --json

# Combine label scope with a query
nylas email search "stripe" --in Receipts --json

여러 계정에 걸친 페이지네이션

프로덕션 동기화 클라이언트는 연결된 사서함을 여러 개 다루는 경우가 많습니다 — 공유 받은편지함 4개를 집계하는 세일즈 옵스, 사용자 계정 5개를 다루는 AI 에이전트, 워크스페이스의 모든 계정에서 이메일 신호를 끌어오는 CRM처럼요. Gmail API는 OAuth 그랜트별로 할당량을 적용하므로 계정 10개를 병렬로 동기화해도 계정 간 스로틀링은 없지만, 애플리케이션 코드는 10개의 개별 리프레시 토큰, 10개의 토큰 만료 타이머, 10개의 historyId 체크포인트를 관리해야 합니다.

CLI에서는 그랜트가 일급 객체입니다. nylas auth list는 연결된 모든 계정을 보여줍니다. nylas auth whoami는 다음 명령이 어떤 그랜트를 사용할지 출력합니다. nylas auth switch는 활성 그랜트를 변경합니다. 이메일과 캘린더 명령은 선택적 위치 인자로 그랜트 ID도 받으므로, 셸 스크립트 하나로 활성 상태를 전환하지 않고도 그랜트를 순회할 수 있습니다.

# Show every connected grant as JSON
nylas auth list --json

# Run the same sync across every Google grant
for grant in $(nylas auth list --json | jq -r '.[] | select(.provider == "google") | .id'); do
  nylas email search "*" "$grant" --after 2026-05-01 --json
done

CI, 크론 잡, 헤드리스 환경에서 동기화하기

Gmail API의 OAuth2 브라우저 팝업은 CI, Docker 컨테이너, AI 에이전트 샌드박스를 비롯한 모든 무인 환경에서 결정적인 차단 요소입니다. Google의 오프라인 액세스 플로는 애플리케이션이 일회성 대화형 설정 중에 리프레시 토큰을 확보한 뒤, 시크릿 매니저에 저장하고 프로그래밍 방식으로 갱신할 것을 요구합니다. 권장 대안(도메인 전체 위임을 사용하는 서비스 계정)은 Google Workspace 관리자만 쓸 수 있고 워크스페이스 수준의 설정 변경이 필요합니다.

Nylas CLI는 API 키 인증으로 브라우저를 완전히 우회합니다. nylas auth config --api-key는 브라우저를 건드리지 않고 키를 로컬에 저장합니다. nylas auth token은 후속 API 호출용 범위 제한 베어러 토큰을 생성합니다. nylas auth status는 현재 인증 상태를 보고합니다 — 컨테이너 배포의 헬스 체크에 유용합니다.

# In a GitHub Action or cron job — no browser needed
export NYLAS_API_KEY="nyk_..."
nylas auth config --api-key "$NYLAS_API_KEY"
nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json > /var/log/digest.json

브라우저가 없는 Manus, Replit 등의 AI 에이전트 샌드박스에서도 같은 플로가 적용됩니다 — 에이전트가 키를 한 번 발급해 환경에 보존하면, 이후의 모든 명령이 대화형 단계 없이 실행됩니다.

폴링 대신 웹훅

Gmail 받은편지함을 5분마다 폴링하면 받은편지함 하나당 하루 288번의 API 호출이 발생합니다. 연결된 사용자 1,000명이면 하루 288,000번이고, 대부분은 새 메시지가 없는 응답입니다. Gmail은 Cloud Pub/Sub를 통한 푸시 알림 대안을 제공합니다: Pub/Sub 토픽을 만들고, gmail-api-push@system.gserviceaccount.com에 pubsub.publisher 역할을 부여하고, 각 사서함에 users.watch를 호출하고, Google이 만료시키기 때문에 7일마다 watch를 갱신해야 합니다. 설정 비용이 높고, 갱신을 한 번 놓치면 동기화가 조용히 망가집니다.

CLI의 웹훅은 Pub/Sub 토픽 없이 동작합니다. nylas webhook create는 HTTPS 엔드포인트와 트리거 목록을 등록합니다. nylas webhook list는 등록된 항목을 보여줍니다. nylas webhook triggers는 지원하는 모든 이벤트 유형(message.created, message.updated, thread.replied에 더해 캘린더와 연락처 이벤트)을 출력합니다. nylas webhook test send는 엔드포인트에 샘플 페이로드를 발사해 실서비스 전에 수신기를 검증할 수 있게 합니다. nylas webhook verify는 수신 페이로드의 HMAC 서명을 검증합니다.

# Register a webhook for new message events
nylas webhook create \
  --url https://example.com/hooks/nylas \
  --triggers message.created \
  --json

# Verify a payload from your receiver
nylas webhook verify \
  --payload-file ./incoming.json \
  --signature "$X_NYLAS_SIGNATURE" \
  --secret "$WEBHOOK_SECRET"

웹훅은 실제 이벤트가 있을 때만 발생하며, 일반 사용자라면 보통 받은편지함당 하루 100건 미만입니다. 하루 288,000번이던 폴링 부하는 같은 1,000개 받은편지함 기준 하루 약 100,000건의 이벤트로 줄어들고, 새 메시지 도착부터 애플리케이션이 인지하기까지의 지연 시간은 최대 5분에서 약 1초로 떨어집니다.

다른 이메일 프로바이더의 페이지네이션 처리 방식

페이지네이션 계약을 이해할 가치가 있는 프로바이더는 Gmail만이 아닙니다. Microsoft Graph(Outlook과 Exchange Online)는 클라이언트가 그대로 따라가는 전체 URL인 @odata.nextLink를 사용합니다. IMAP(Yahoo Mail, iCloud Mail, 호스팅 IMAP)은 전통적인 의미의 페이지네이션이 없습니다: UID SEARCH는 일치하는 모든 UID를 응답 하나로 반환하므로 큰 사서함에서는 느릴 수 있지만 클라이언트 측 커서 로직이 사라집니다. Exchange Web Services(구형 Exchange 배포에서 쓰이는 EWS)는 IndexedPageItemView와 BasePoint 오프셋을 사용하는 인덱스 기반 페이징을 씁니다.

프로바이더별 가이드는 같은 페이지네이션 문제를 각 계약에서 어떻게 푸는지 보여줍니다: 커맨드라인에서 Outlook 이메일 목록 보기, Exchange 이메일 목록 보기, Yahoo 이메일 목록 보기, iCloud 이메일 목록 보기, IMAP 이메일 목록 보기. 같은 nylas email list 명령이 동일한 플래그로 모든 프로바이더에서 실행되도록 문서화되어 있습니다.

위에서 설명한 Outlook, Exchange, Yahoo, iCloud, IMAP의 프로바이더 측 동작은 각 프로바이더의 공개 문서에서 가져온 것이며, 모든 백엔드에서 엔드투엔드로 검증된 실행 결과는 아닙니다. 프로바이더별 워크플로를 배포하기 전에 로컬에서 테스트하세요.

Gmail 받은편지함 동기화에는 시간이 얼마나 걸리나요?

가정용 광대역 연결(Google 서버까지 중간값 지연 약 150ms)에서 테스트 사서함을 대상으로 실행한 합성 벤치마크는 수동 페이지네이션과 단일 CLI 명령 사이의 비용 차이를 보여줍니다. Python 루프 열은 429 응답에 대한 지수 백오프를 포함한 messages.list + messages.get 호출입니다. CLI 수치는 같은 내부 호출을 배치 처리하고 병렬화한 것입니다.

할당량 비용은 클라이언트가 아니라 Gmail의 호출당 가격 정책으로 고정됩니다. CLI가 messages.list 호출을 더 싸게 만들 수는 없지만, 페이지네이션과 재시도 동작을 애플리케이션 코드 바깥에 둘 수는 있습니다. 전체 본문 10,000개를 가져오는 단순한 Python 루프는 messages.get 호출만으로 약 200,000 할당량 단위를 씁니다. 새로 전체 동기화를 계획할 때 이 숫자들을 추적하는 것이 중요합니다. 배치와 동시성을 제어하는 플래그는 nylas email list를 참조하세요.

자주 쓰는 레시피

이메일 페이지네이션을 표준 UNIX 도구와 결합한 셸 패턴 4가지입니다. 각각 JSON 출력 파싱에 jq를, 기계가 읽을 수 있는 형식에 --json을 사용합니다.

읽지 않은 이메일 전부 세기

nylas email list --unread --json을 jq 'length'로 파이프하면 숫자 하나를 얻습니다. 스크립트형 대시보드나 온콜 알림에 유용합니다. watch -n 60과 결합하면 1분마다 새로 고치는 라이브 카운터가 됩니다. JSON 출력은 자동으로 페이지네이션되므로 래퍼에서 nextPageToken을 처리할 필요가 없습니다.

nylas email list --unread --json | jq 'length'

일일 다이제스트 크론 잡

크론으로 하루에 한 번 실행되는 다이제스트 스크립트는 nylas email search에 어제 날짜를 묶은 --after를 사용하고, JSON을 임시 파일에 덤프한 뒤, 메시지당 한 줄짜리 요약을 mail로 파이프합니다. 크론이 도는 머신에서는 nylas auth login을 nylas auth config --api-key로 교체해 브라우저가 필요 없게 만드세요.

# /etc/cron.daily/email-digest.sh
yesterday=$(date -u -v-1d +%Y-%m-%d)
nylas email search "*" --after "$yesterday" --json > /tmp/digest.json
jq -r '.[] | "\(.from) - \(.subject)"' /tmp/digest.json \
  | mail -s "Daily digest" you@example.com

특정 발신자가 보낸 첨부 파일 있는 이메일 전부 찾기

nylas email search와 nylas email attachments list를 연결하면 파이프라인 하나로 한 발신자의 모든 첨부 파일을 찾을 수 있습니다. email search가 --from과 --has-attachment 필터를 서버 측에서 적용하고, attachments list가 일치 항목을 하나씩 열거합니다. 파일을 디스크에 받고 싶으면 nylas email attachments download로 파이프하세요.

nylas email search "*" --from billing@stripe.com --has-attachment --json \
  | jq -r '.[].id' \
  | xargs -I{} nylas email attachments list {} --json

최근 로그인 이메일에서 OTP 코드 자동 추출

어제 이후 수신된 로그인 관련 이메일을 모두 가져와 본문에서 6자리 숫자를 추출하고 첫 번째 일치 항목을 출력합니다. 키워드 쿼리 verification이 가장 흔한 트랜잭션 메일 제목을 잡아내며, 다른 발신자를 다루려면 OTP나 code로 다시 실행하세요. 이 패턴은 전용 OTP 추출 가이드의 기초입니다. 단순 집계를 넘는 받은편지함 분석은 nylas email ai analyze를 참조하세요. PowerShell 사용자는 PowerShell 이메일 리포트에서 이 패턴들을 응용할 수 있습니다.

nylas email search "verification" \
  --after "$(date -u -v-1d +%Y-%m-%d)" \
  --json \
  | jq -r '.[].body' \
  | grep -oE '[0-9]{6}' \
  | head -1

나란히 비교하기

아래 표는 프로덕션에서 중요한 9가지 역량에 걸쳐 Gmail API Python 방식과 Nylas CLI를 비교합니다. 가장 큰 차이는 설정 시간입니다: Gmail API 경로는 15-20분의 콘솔 설정과 80-120줄의 코드를 요구하는 반면, CLI는 설치와 인증에 약 2분이 걸립니다.

자주 묻는 질문

Gmail API의 nextPageToken은 무엇인가요?

messages.list를 호출하면 Gmail API는 페이지당 최대 500개의 결과를 반환합니다. 메시지가 더 있으면 응답에 nextPageToken 문자열이 포함됩니다. 그 토큰을 다음 요청의 pageToken 파라미터로 전달해 다음 페이지를 가져옵니다. 응답에 nextPageToken이 더 이상 포함되지 않을 때까지 반복하며, 토큰이 없으면 끝에 도달했다는 뜻입니다.

Gmail 증분 동기화는 historyId로 어떻게 동작하나요?

Gmail 사서함의 모든 변경(새 메시지, 삭제, 라벨 변경)에는 단조 증가하는 historyId가 부여됩니다. 마지막 동기화의 historyId를 저장한 뒤 startHistoryId와 함께 history.list를 호출하면 그 이후의 변경 사항만 받습니다. 히스토리 ID는 대략 30일이 지나면 만료됩니다. 저장한 ID가 너무 오래되면 API가 404를 반환하고 전체 동기화 폴백이 필요합니다.

Gmail API 설정 없이 Gmail 이메일 목록을 볼 수 있나요?

네. Nylas CLI는 OAuth2와 프로바이더 인증을 내부에서 처리합니다. nylas email list --limit 50 --json을 실행하면 Google Cloud에 Gmail API 클라이언트를 등록하거나, OAuth 동의 화면을 구성하거나, 액세스 토큰을 관리하지 않고도 Gmail 받은편지함을 나열할 수 있습니다. CLI는 6개 프로바이더에서 같은 방식으로 동작합니다.

CLI가 Gmail API 레이트 리밋을 처리하나요?

네. Gmail API는 신규 프로젝트에 프로젝트별·사용자별 분당 할당량 6,000단위를 주고, messages.list 호출은 5단위입니다. CLI는 레이트 리밋, 페이지네이션, 토큰 갱신, 재시도 로직을 내부에서 관리합니다. 할당량 추적이나 백오프 코드를 한 줄도 쓰지 않고 결과를 얻습니다.

메시지 대신 Gmail 스레드를 페이지네이션할 수 있나요?

네. nylas email threads list는 messages.list 대신 threads.list 엔드포인트를 페이지 단위로 순회합니다. 일반적인 사서함에서는 메시지 3-4개당 스레드가 대략 1개이므로 페이지 수가 60-80% 줄어듭니다. nylas email threads mark와 결합하면 대화의 모든 메시지를 명령어 하나로 읽음 처리할 수 있습니다.

특정 Gmail 라벨의 이메일만 보려면 어떻게 하나요?

nylas email search의 --in에 라벨 이름을 전달하세요. nylas email search "*" --in Receipts --json 명령은 Receipts 라벨이 붙은 메시지만 반환합니다. 계정의 모든 라벨 또는 폴더를 보려면 nylas email folders list를 사용하세요. 같은 플래그가 문법 변경 없이 Outlook 폴더, Yahoo IMAP 폴더, iCloud 폴더에도 적용됩니다.

OAuth 팝업 없이 크론 잡에서 Gmail을 동기화할 수 있나요?

네. nylas auth login 대신 nylas auth config --api-key를 사용하세요. API 키 플로는 브라우저를 열지 않으므로 헤드리스 머신, Docker 컨테이너, CI 파이프라인, Manus 같은 AI 에이전트 샌드박스에서 실행됩니다. 크론 잡이 실행되는 환경에 키를 시크릿으로 저장하세요.

최근 24시간 동안의 이메일만 동기화하려면?

nylas email search에 --after를 전달하세요. 최근 24시간이라면: nylas email search "*" --after $(date -u -v-1d +%Y-%m-%d) --json. 이 플래그는 YYYY-MM-DD 날짜를 받고, CLI가 하부 프로바이더가 사용하는 필터 문법으로 변환합니다 — Gmail이라면 API에 대한 q=after: 쿼리가 됩니다.

CLI가 Outlook, Yahoo, iCloud에서도 같은 방식으로 동작하나요?

네. 같은 nylas email list, nylas email search, nylas email read 명령이 Gmail, Outlook, Exchange, Yahoo, iCloud, IMAP에서 동작합니다. 이 도구는 각 명령을 프로바이더별 API 호출로 변환합니다: Gmail의 REST API, Microsoft Graph, IMAP UID SEARCH, 또는 EWS. 프로바이더별 안내는 Outlook 이메일 목록 보기, IMAP 이메일 목록 보기, Exchange 이메일 목록 보기에 있습니다.

historyId가 30일을 넘기면 어떻게 되나요?

Gmail이 history.list에서 404를 반환하고, 전체 페이지네이션 동기화로 폴백해야 합니다. CLI는 이 폴백을 자동으로 처리합니다 — 404를 볼 일도 없고 두 코드 경로를 작성할 필요도 없습니다. ETag 기반 동시성 제어와 If-Match 처리는 Gmail API If-Match와 ETag 처리에서 다룹니다.

폴링 대신 푸시 알림을 받을 수 있나요?

네. nylas webhook create는 Cloud Pub/Sub 토픽이나 Google Workspace 관리자 없이 message.created, thread.replied 같은 이벤트를 위한 HTTPS 엔드포인트를 등록합니다. 지원하는 모든 이벤트 유형을 보려면 nylas webhook triggers를 실행하세요.

다음 단계

Gmail 페이지네이션과 증분 동기화는 가장 흔한 API 통합 과제 둘이지만, 전부는 아닙니다. 아래 관련 가이드는 이메일 전송, ETag 기반 동시성 제어, 전체 CLI 명령어까지 인접한 워크플로를 다룹니다.

• 커맨드라인에서 Gmail 이메일 목록 보기 — 발신자, 제목, 날짜, 읽음 상태로 필터링
• 커맨드라인에서 Gmail 보내기 — Gmail API 클라이언트 코드나 SMTP 설정 없는 Gmail 전용 전송
• Gmail API 검색 쿼리 예제 — q, 라벨, 카테고리, 첨부 파일, CLI 대응 명령
• historyId와 ETag를 사용한 Gmail API 증분 동기화 — ETag, If-Match, 412 처리 심층 분석
• 2026년 Gmail API 할당량 — 현행 할당량 단위, 메서드별 비용, 과금 기준, 에이전트에 안전한 패턴
• Gmail API가 AI 에이전트를 망가뜨리는 이유 — OAuth 프롬프트, 페이지네이션 상태, MIME 파싱, 할당량 압박
• AI 에이전트를 위한 이메일 API 비교 — Gmail, Microsoft Graph, IMAP, 프로바이더 중립 API 트레이드오프
• Google Calendar API 페이지네이션과 동기화 — 같은 패턴을 events.list와 syncToken에 적용
• 로컬에서 이메일 웹훅 테스트하기 — 폴링 루프를 교체하기 전에 이벤트 기반 동기화 검증
• 커맨드라인에서 Outlook 이메일 목록 보기 — @odata.nextLink를 사용하는 Microsoft Graph 페이지네이션
• 커맨드라인에서 IMAP 이메일 목록 보기 — UID SEARCH를 통한 Yahoo, iCloud, 호스팅 IMAP
• 터미널에서 이메일 보내기 — bash, zsh, 크로스 플랫폼 전송 워크플로
• 이메일에서 OTP 코드 추출하기 — 스크립트에서 인증 코드 조회 자동화
• PowerShell 이메일 리포트 — 같은 페이지네이션 패턴을 Windows 셸에 맞게 응용
• 시작하기 — 설치 방법(Homebrew, 셸 스크립트, PowerShell, Go)과 최초 인증
• 전체 명령어 레퍼런스 — 모든 플래그와 서브커맨드 문서화