Guide

IMAP 없이 앱에 이메일 동기화 추가하기

이메일 동기화를 만들면 보통 사서함마다 지속적인 IMAP IDLE 연결을 유지하고, OAuth 갱신과 대규모 재연결 처리를 해야 합니다. 이 가이드는 이를 대체하는 패턴을 보여줍니다. 새 메일은 Webhook으로 받고, 백필은 온디맨드 읽기로 처리하며, 전체 흐름을 터미널에서 프로토타이핑합니다.

Written by Caleb Geene Director, Site Reliability Engineering

Reviewed by Qasim Muhammad

Verified — CLI 3.1.17 · Gmail, Outlook, IMAP · last tested June 9, 2026

IMAP 동기화 인프라 구축은 왜 어렵나요?

IMAP 동기화가 어려운 이유는 실시간 전달을 위해 모든 사서함마다 지속적인 IDLE 연결을 열어 두어야 하기 때문입니다. RFC 2177에 따르면 클라이언트는 최소 29분마다 IDLE을 다시 발행해야 하며, 그렇지 않으면 서버가 연결을 끊을 수 있습니다. 따라서 사용자 10,000명은 장시간 유지해야 하는 socket 10,000개를 의미하고, 이를 살리고, 재연결하고, 프로세스 간에 재분산해야 합니다.

그 위에는 계정별 OAuth token refresh, XOAUTH2 인증, provider별 차이, 노드가 재시작될 때 수천 개 사서함이 한 번에 다시 handshake하는 재연결 폭풍이 올라갑니다. 메시지 하나를 parse하기 전에 수 주 분량의 인프라를 만들어야 하는 셈입니다 — 새벽 3시에 호출을 만드는 것도 만들려던 기능이 아니라 이 부분입니다.

IMAP 동기화를 무엇으로 대체하나요?

대체 방식은 push-plus-pull 모델입니다. 새 메일이 도착하면 webhook이 작은 알림을 전달하고, 앱은 내용이 필요할 때만 메시지를 온디맨드로 읽습니다. 지속 연결은 하나도 유지하지 않습니다. Provider가 변경을 알려 주면 필요한 항목만 가져옵니다. Gmail과 Microsoft Graph의 push 모델도 내부적으로 이 방식으로 동작합니다.

이 방식은 비용 구조를 뒤집습니다. 수천 개의 idle socket을 계속 따뜻하게 유지하는 대신, 새 메시지당 저렴한 webhook 하나와 실제로 사용하는 read 비용만 냅니다. 하루에 50개의 메시지를 받는 사서함은 50개의 알림 비용만 들며, 24시간 유지되는 연결 비용이 아닙니다.

IMAP 없이 이메일 동기화를 어떻게 프로토타이핑하나요?

터미널에서 두 개의 명령으로 전체 패턴을 프로토타이핑할 수 있습니다. message.created webhook을 등록해 새 메시지마다 endpoint가 알림을 받게 하고, 내장 receiver를 실행해 payload가 도착하는 것을 확인합니다. Server framework도, socket pool도 필요 없습니다 — 앱이 처리할 정확한 push 형태를 볼 수 있습니다.

# 1. Push new mail to your endpoint
nylas webhook create \
  --url https://your-app.example.com/inbound \
  --triggers message.created \
  --description "email sync"

# 2. Watch payloads locally while you build the handler
nylas webhook server --port 9000

알림이 도착하면 메시지 본문을 온디맨드로 가져옵니다. nylas email read 명령은 webhook의 message ID를 받아 전체 내용을 JSON으로 반환합니다 — 필요한 경우에만 수행하는 유일한 fetch입니다.

# In your handler: fetch just the message the webhook pointed at
nylas email read "$MESSAGE_ID" --json | jq '{from: .from, subject: .subject}'

기존 메일은 어떻게 백필하나요?

히스토리는 전체 동기화가 아니라 온디맨드 검색으로 백필합니다. nylas email search 명령은 사서함을 직접 조회하고, --after 날짜 필터는 가져오기 범위를 최근 구간으로 제한해 필요 없는 수년치 메일을 끌어오지 않게 합니다. 대부분의 앱은 onboarding 시점에 최근 30–90일만 필요합니다.

# One-time backfill of the last 30 days at user onboarding
nylas email search "*" --after 2026-05-10 --json > backfill.json
jq 'length' backfill.json

언제 여전히 IMAP이 필요한가요?

사서함에 현대적인 API가 없을 때는 여전히 IMAP이 필요합니다 — 자체 호스팅 Dovecot 서버, 레거시 호스트, IMAP만 제공하는 niche provider가 예입니다. 이런 경우 구독할 webhook이 없으므로 polling 또는 IDLE client가 불가피합니다. 솔직한 trade-off는 push 모델에는 알림을 지원하는 provider가 필요하다는 점입니다.

그래도 CLI는 같은 명령 표면으로 일반 IMAP 계정에 연결하므로, IMAP client를 직접 작성하지 않고도 통합된 읽기 모델을 얻을 수 있습니다. 대부분의 팀은 IMAP 없는 경로가 Gmail, Outlook, 주요 provider를 포괄한다는 것을 알게 됩니다 — 실제 사용자의 대부분입니다 — 그리고 long tail에는 polling fallback을 남깁니다.

다음 단계