로컬 우선(Local-first) AI를 사용하여 10년 된 메일함을 정리하는 오픈 소스 도구를 만들었습니다

10년의 세월을 삼킨 메일함

저는 소프트웨어 아키텍트(Software Architect, 약 10년 차)이기 때문에, 본능적으로 '분명히 도구가 있을 것'이라고 생각했습니다. 하지만 실제로는 없었습니다. 흩어져 있는 Python 스크립트나 거의 방치된 몇몇 유틸리티들은 있었지만, 완전하고 안전한 제품이라고 느껴지는 것은 없었습니다. 예를 들어, "이 40명의 발신자로부터 온 모든 메일을 보여주고, 각각 몇 개인지 알려준 뒤, 내가 손대기 전에 미리 볼 수 있게 해줘"라고 말하거나, 더 나아가 "내 편지함 전체를 클라우드로 전송하지 않고도, 무엇이 스팸인지 파악해서 알아서 정리해줘"라고 요청할 수 있는 그런 제품 말입니다.

그래서 저는 저 자신을 위해 IMAP을 이용한 Python 코드 몇 줄을 작성했습니다. 그러다 보니 기능이 계속 늘어났고, 이를 제대로 완성하여 오픈 소스로 공개하기로 결정했습니다: 바로 IMAP Cleanup Tool입니다.

pip install "imap-cleanup-tool[web,ai]" 실행 후 imap-cleanup-tool-web
Repo: https://github.com/mrpickles007/imap-cleanup-tool
Site: https://imapcleanuptool.com

핵심 기능: 로컬 우선(Local-first)으로 실행되는 AI 정리

제가 가장 자랑스럽게 생각하는 기능은 AI Cleanup입니다. "이 중에서 실제로 내가 원하는 것은 무엇인가?"라는 질문을 모델에게 안전하고 효율적으로 던지는 기능입니다. 핵심적인 설계 선택은 **개별 이메일이 아닌, 발신자별로 집계된 통계(aggregated per-sender statistics)**를 기반으로 작동한다는 점입니다. 메일함 전체를 LLM(Large Language Model)에 입력하지 않습니다(그렇게 하면 속도가 느려지고 토큰(token) 수가 폭발할 것입니다). 로컬 휴리스틱(local heuristic)이 대부분의 작업을 수행하며, 경계선에 있는 **발신자(senders)**의 짧은 목록만이 모델에 전달됩니다.

LLM은 경계선에 있는 사례(borderline cases)만 확인합니다. 설정한 임계값(threshold)에 도달하거나 그보다 높은 발신자들만 모델로 전송되며, 각 발신자당 몇 개의 제목 샘플(sample subjects)(및 통계 정보)만 전달됩니다. 메시지 본문(message body)은 절대 전송되지 않습니다. 모델은 무엇을 삭제할지 결정하는 엄격한 JSON 판결(Pydantic으로 검증되며, 잘못된 출력 시 재시도됨)을 반환합니다.
사용자가 통제권을 유지합니다. 보고 전용(Report only) 모드는 무엇이 삭제될지를 정확히 보여주기만 하며 아무것도 변경하지 않습니다. 실제로 삭제하는 것은 별도의 의도적인 단계이며, 기본적으로 비활성화(off by default)되어 있습니다.

💸 비용은 얼마나 드나요? 제 테스트 결과, gpt-4o-mini를 사용하여 약 40,000개의 메시지가 담긴 Gmail을 정리하는 데 **약 0.03유로(€0.03)**가 소요되었으며, 약 5분 만에 약 13,000개의 이메일을 삭제했습니다. 임계값을 넘는 발신자만 LLM에 접근하므로(각각 몇 개의 제목만 전달), 비용은 매우 낮게 유지됩니다. 또한 로컬 Ollama 모델을 사용하면 무료입니다. 심지어 실행할수록 비용이 더 저렴해집니다. 이미 스팸으로 저장된 발신자는 이후 실행 시 모델 호출에서 제외되므로, 각 정리 작업마다 이전보다 더 적은 주소가 전송됩니다.

이 도구를 제가 실제로 제 편지함에 사용할 수 있게 만드는 두 가지 요소는 다음과 같습니다:

로컬 우선(Local-first). Ollama를 통해 무료 로컬 모델을 설정할 수 있으며(ollama/llama3가 즉시 작동함), 제목, 통계, 그 무엇도 사용자의 기기를 벗어나지 않습니다.
BYOA (Bring Your Own API key). 클라우드 모델을 선호하시나요? OpenAI, OpenRouter, 또는 litellm이 지원하는 무엇이든 본인의 API 키를 사용하여 연결할 수 있습니다. 선택 사항인 모델별 비용 추적 기능을 통해 각 실행에 드는 비용을 확인할 수 있습니다.
RFC 8058 원클릭 HTTPS POST.

필요한 곳에 적용되는 현대적인 인증 (OAuth2)

Microsoft는 개인용 및 365 계정에 대해 IMAP/SMTP를 통한 비밀번호 로그인을 차단했으며, 이는 많은 오래된 도구들을 조용히 망가뜨리고 있습니다. 그래서 "Microsoft로 로그인" 기능이 내장되어 있습니다. 이는 OAuth2 디바이스 코드 (device-code) 흐름(URL을 열고 짧은 코드를 입력하는 방식)을 사용하며, 비밀번호 없이 오직 **암호화된 리프레시 토큰 (encrypted refresh token)**만을 저장하고 XOAUTH2로 인증합니다. 이 방식은 메일 읽기(IMAP), 알림 메일 전송(SMTP), 그리고 액세스 토큰이 리프레시 토큰으로부터 조용히 생성되기 때문에 **무인 예약 작업 (unattended scheduled jobs)**에도 작동합니다. 저는 벤더 SDK 없이 표준 라이브러리(urllib / imaplib / smtplib)만으로 이를 구현했으며, 디바이스 코드 흐름은 localhost 리다이렉트가 필요하지 않으므로 헤드리스(headless) 환경이나 SSH를 통해서도 작동합니다.

그 외의 모든 제공업체(Gmail, Yahoo, iCloud, 개인 도메인)는 일반 비밀번호나 앱 비밀번호로 연결됩니다. 그리고 OAuth 제공업체 정보는 JSON 설정 파일 (JSON config file)(엔드포인트, 클라이언트 ID, 선택적 시크릿, 스코프)에 저장되므로, Google을 추가하거나 — 기업 배포를 위해 원하는 설정인 — **자사 조직의 앱 등록 (organization's app registration)**으로 도구를 지정하는 것은 코드 변경이 아닌 설정 편집만으로 가능합니다.

제어권을 원할 때도 여전히 정밀한 수동 도구입니다

AI는 선택 사항입니다. 내부적으로는 여전히 완전하고 스크립트 작성이 가능한 IMAP 클리너입니다:

누가 당신을 괴롭히는지 확인하세요. 모든 발신자와 각 발신자가 보낸 이메일 수를 순위별로 정리하여 CSV로 내보냅니다.
무엇이든 기준으로 매칭하세요. 발신자, 도메인, 또는 시각적 빌더로 구축된 **중첩된 AND/OR 규칙 (nested AND/OR rules)**을 사용하세요. 암기해야 할 쿼리 구문은 없습니다.
수정하기 전에 확인하세요. 기본적으로 드라이 런 (dry-run) 모드를 제공합니다.
삭제 대신 이동하세요. 매칭된 항목을 다른 폴더(또는 Gmail 라벨)로 보내거나, 즉석에서 폴더를 생성/삭제할 수 있습니다. 완전히 삭제(nuking)하는 대신 아카이빙(archiving)하기에 매우 좋습니다.
대용량 폴더에서도 빠릅니다. 서버 측 IMAP 검색과 **배치 삭제 (batched deletes)**를 통해 작동합니다.
이메일 알림: 작업이 완료되면 AI 보고서가 CSV로 첨부된 메일을 받을 수 있습니다.
Web UI 및 CLI (CLI에서도 AI 기능과 완전히 동일한 성능 제공), 그리고 첫 실행 시 가이드 투어를 제공합니다.
스케줄링: 정기적인 정리를 위해 OS(작업 스케줄러 / cron)를 통한 스케줄링을 지원하며, 예약된 AI 작업도 포함됩니다.
로컬 전용 (Local-only). 사용자의 자격 증명은 절대 기기를 떠나지 않습니다. 클라우드도, 추적도 없습니다.

60초 투어

AI가 보고서를 작성하도록 합니다 (아무것도 삭제되지 않습니다):

imap-cleanup-tool --host imap.gmail.com --user you@gmail.com \
    --ai-cleanup --ai-report-only --ai-report-csv report.csv

수동 방식으로 가장 심각한 위반자를 찾습니다:

imap-cleanup-tool --host imap.gmail.com --user you@gmail.com --list-senders --save-senders senders.csv

규칙 기반 정리를 미리 보기 합니다 (아무것도 변경되지 않습니다):

imap-cleanup-tool --host imap.gmail.com --user you@gmail.com \
    --targets junk.txt --dry-run

삭제 대신 아카이빙하세요 - 매칭된 항목을 폴더/라벨로 이동합니다:

imap-cleanup-tool --host HOST --user USER --create-folder "Archive/2013"
imap-cleanup-tool --host HOST --user USER --targets old.txt \
    --move --dest-folder "Archive/2013" --dry-run

또는 클릭하는 것을 선호한다면 Web UI인 imap-cleanup-tool-web을 사용하세요.

제가 실제로 신경 쓰는 부분: 어떻게 만들어졌는가

이 부분이 바로 엔지니어링 실력을 보여주는 대목입니다. 왜냐하면 무언가가 만들어진 _방식_이 단순한 스크립트와 당신의 메일함을 믿고 맡길 수 있는 도구 사이의 차이를 만들기 때문입니다.

UI에 구애받지 않는 핵심(core)입니다. 모든 IMAP 로직은 인자 파싱이나 HTML에 대해 아무것도 알지 못하는 단일 모듈에 존재합니다. 이 모듈은 Python 표준 라이브러리(imaplib)만을 사용하기 때문에, CLI는 런타임 종속성(runtime dependencies)이 전혀 없습니다; 웹 UI ([web])와 AI 기능 ([ai])은 선택적이고 지연 로딩되는 추가 기능입니다. 두 프론트엔드는 동일한 핵심을 호출하므로, 논리가 중복되거나

투명성에 관한 참고 사항: 저는 이 도구를 직접 설계 및 아키텍처를 구성했으며, 코드 작성을 가속화하기 위해 AI 어시스턴트를 사용했습니다. 생성된 코드를 맹목적으로 신뢰하기보다는 테스트 스위트 (test suite)와 CI에 의존했습니다. 모든 코드는 직접 읽어보실 수 있도록 공개되어 있습니다. (이는 제품 자체의 AI Cleanup 기능과는 별개의 사항입니다.)

설치 (Install)

# Python 3.10+; [web,ai]는 CLI 위에 웹 UI + AI Cleanup 기능을 추가합니다
pip install "imap-cleanup-tool[web,ai]"
imap-cleanup-tool-web        # 로컬 웹 UI를 엽니다

모든 것은 로컬에서 이루어집니다. AI의 경우, 로컬 Ollama 모델을 지정하거나 (데이터가 기기 외부로 나가지 않습니다) 본인의 클라우드 API 키를 붙여넣으세요. Gmail의 경우, 앱 비밀번호 (실제 비밀번호가 아닌)를 사용하면 준비가 완료됩니다. AI가 필요하지 않으신가요? pip install "imap-cleanup-tool[web]"를 사용하세요.

향후 방향 / 기여하기 (Where it's going / contributing)

이 프로젝트는 AGPL-3.0 라이선스를 따르며, 이슈 템플릿 (issue templates)과 기여 가이드 (contributing guide)가 마련되어 있습니다. Gmail이 아닌 다른 제공업체의 예외 케이스 (edge cases), 더 많은 규칙 필드 (rule fields), 번역, 그리고 AI 단계에서 어떤 로컬 모델이 잘 작동하는지에 대한 피드백 등 많은 도움을 받고 싶습니다. 직접 사용해 보신다면 GitHub 스타 (star)를 눌러주시는 것이 진심으로 큰 도움이 되며, 버그 리포트 (bug reports)와 기능 요청 (feature requests)은 모두 읽고 답변해 드립니다.

저장소 (Repo): https://github.com/mrpickles007/imap-cleanup-tool
사이트 (Site): https://imapcleanuptool.com

이상입니다. 이 도구가 여러분의 편지함을 깨끗하게 되찾아 주기를 바랍니다. 피드백, 이슈 (issues), 그리고 PR (Pull Requests)은 모두 읽고 답변해 드립니다.