Mail Classifier

Gmail LLM 자동 분류·라벨링 — 룰 기반 필터와 AI 판단의 하이브리드

Gmail LLM auto-classification & labeling — hybrid rule-based filter + AI judgment

2026-04-20 프로젝트 Project Python Gmail API

개요 Overview

Mail Classifier는 Gmail 수신 메일을 자동으로 분류하고 라벨을 붙이는 AI 에이전트입니다. 패턴 기반 1차 필터가 명확한 케이스를 빠르게 처리하고, 판단이 모호한 메일만 LLM에게 넘겨 비용과 지연을 최소화합니다.

Mail Classifier is an AI agent that automatically classifies and labels incoming Gmail messages. A pattern-based first-pass filter handles clear-cut cases quickly, passing only ambiguous messages to the LLM — minimizing cost and latency.

🧰

모든 분류 결정은 Gmail 라벨로 즉시 반영됩니다. 삭제·이동이 아닌 라벨 방식이므로 오분류 복구가 쉽고 사용자가 언제든 재학습 데이터로 활용할 수 있습니다.

All classification decisions are applied immediately as Gmail labels. Using labels (not deletion or moving) makes recovery from misclassification easy and allows users to use results as retraining data at any time.

처리 흐름 Processing Flow

Gmail 수신

Gmail Inbox

→

룰 필터

Rule Filter

→

LLM 판단

LLM Judge

→

라벨 적용

Apply Label

→

완료

Done

단계	Stage	처리 방식	Method	대상	Target
1단계 룰 필터	Rule Filter	발신자·도메인·제목 패턴 매칭	Sender/domain/subject pattern matching	명확한 광고·자동발송·알림	Clear ads, auto-sends, notifications
2단계 LLM 판단	LLM Judge	메일 본문 요약 + 카테고리 분류 프롬프트	Body summarization + category classification prompt	룰로 처리 안 된 나머지	Messages not handled by rules
3단계 라벨 적용	Apply Label	Gmail API로 라벨 생성 및 부착	Create and apply label via Gmail API	전체	All

스택 Stack

기술	Tech	역할
`Python 3.11`	에이전트 파이프라인 및 스케줄러	Agent pipeline and scheduler
`Gmail API (Google)`	메일 조회, 라벨 생성·적용	Mail fetch, label create & apply
`Claude / Gemini`	모호한 메일 분류 판단	Ambiguous message classification
`SQLite`	처리 이력, 룰 테이블, 오분류 로그	Processing history, rule table, misclassification log
`GitHub Actions`	주기적 실행 (15분 간격 cron)	Periodic execution (15-min cron)

분류 카테고리 Classification Categories

라벨	Label	설명
`AI/Important`	즉시 읽어야 할 중요 메일	Must-read important messages
`AI/Newsletter`	뉴스레터·구독 콘텐츠	Newsletters and subscription content
`AI/Notification`	서비스 자동 알림·영수증	Service notifications and receipts
`AI/Promo`	마케팅·프로모션 메일	Marketing and promotional mail
`AI/Review`	LLM이 판단 보류한 메일 (수동 검토 대기)	Messages where LLM deferred judgment (pending manual review)

주요 특징 Key Features

비용 최소화: 룰 필터가 명확한 케이스(광고·알림 등)를 먼저 처리하여 LLM 호출을 전체의 20~30% 수준으로 제한
안전한 라벨 방식: 원본 메일을 이동·삭제하지 않고 라벨만 부착하여 오분류 시 즉시 복구 가능
오분류 피드백 루프: 사용자가 라벨을 수정하면 SQLite 로그에 기록되어 룰 개선 또는 재학습 데이터로 활용
판단 보류(AI/Review): LLM이 확신하지 못하는 메일은 즉시 라벨링 대신 검토 큐에 넣어 오분류 위험 감소

Cost minimization: Rule filter handles clear cases (ads, notifications) first, limiting LLM calls to ~20–30% of total volume
Safe label approach: Labels are applied without moving or deleting originals — easy recovery on misclassification
Misclassification feedback loop: When users correct labels, changes are logged to SQLite for rule improvements or retraining
Judgment deferral (AI/Review): LLM-uncertain messages go to a review queue instead of immediate labeling, reducing misclassification risk