gmail-butler

작성 2026-07-06읽는 시간 9분

AI 없이 메일함을 대신 정리하는 0원 집사

gmail-butler 개념 인포그래픽 — 쏟아져 들어온 메일을 집사가 규칙(광고·뉴스레터·금융 키워드)으로 판정해, 중요한 메일만 즉시 알리고 나머지는 라벨 서랍에 정리하는 흐름. AI 없음 · 0원

이건 뭐예요?

먼저 제 얘기를 잠깐 할게요. 저는 목재 가공 회사를 운영하는 사장입니다. 코드는 한 줄도 못 씁니다. 그런데 회사는 AI로 돌아가요. 오늘 소개할 건 그중에서도 제 메일함을 지키는 도구예요. 이론이 아니라, 지금 이 순간에도 제 회사 메일함에서 실제로 돌고 있는 물건입니다.

아침에 출근해서 메일함을 열면 하루에 수십 통이 와 있어요. 카드 결제 알림, 쇼핑몰 광고, 뉴스레터, "상위노출 도와드립니다" 같은 영업 메일. 그런데 그 사이에 거래처의 견적 요청 한 통과 관공서 지원사업 공문 한 통이 끼어 있습니다. 이걸 골라내느라 매일 아침 약 30분(체감)을 썼어요. 어느 날은 광고를 지우다가 견적 요청 메일을 같이 지울 뻔했습니다. 그 순간 등에서 식은땀이 났어요. 제조업에서 견적 메일 하나 놓치면 그게 곧 매출이니까요.

gmail-butler(지메일 버틀러) 는 이름 그대로 메일함 집사예요. 좋은 집사를 떠올려 보세요. 우편함에 꽂힌 전단지는 알아서 폐지함으로, 고지서는 서랍에 차곡차곡, 그리고 등기 우편이 오면 그 자리에서 "사장님, 이건 지금 보셔야 합니다" 하고 가져다줍니다. gmail-butler 가 하는 일이 정확히 이거예요.

기본 정보부터 정리해 드릴게요.

항목	내용
정식명	gmail-butler
GitHub	digiwood7/gmail-butler
만든이	접니다 (코드는 못 쓰니까, AI와 함께 만들었어요)
스택	파이썬 3.8 이상 + 구글 공식 SDK 3개
라이선스	MIT (자유롭게 쓰고 고쳐도 되는 너그러운 오픈소스 라이선스)
공개일	2026-07-06
비용	0원 — AI(LLM)를 안 쓰니까 토큰 비용이 없어요

여기서 제일 중요한 특징이 하나 있어요. 이 도구는 AI를 쓰지 않습니다. "AI로 돌아가는 회사라면서 왜 AI를 안 써요?" 싶으시죠. 이유는 간단해요. 메일 분류는 규칙(키워드)만으로 충분하거든요. 그리고 AI를 안 쓰면 좋은 점이 두 가지 생깁니다.

비용이 0원이에요. LLM(대형 언어 모델, 챗GPT 같은 인공지능)을 부르면 부를 때마다 토큰 비용이 나가요. 30분마다 돌리는 도구라면 이게 쌓입니다. gmail-butler 는 키워드 비교만 하니까 아무리 돌려도 공짜예요.
메일 본문이 밖으로 안 나가요. AI 분류 앱은 메일 내용을 AI 회사 서버로 보내서 판단을 받아요. gmail-butler 는 전부 내 컴퓨터 안에서 끝납니다(로컬 완결). 거래처 견적서, 계약 내용이 담긴 메일을 남의 서버에 보내지 않아도 돼요.

동작 원리는 5단계 우선순위예요. 메일 하나하나를 위에서부터 순서대로 판정하고, 위 단계에서 걸리면 아래는 보지 않습니다.

화이트리스트(whitelist) — 상사·거래처처럼 절대 놓치면 안 되는 발신자. 어떤 규칙에도 걸리지 않고 무조건 받은편지함에 남아요.
must_see(중요 키워드) — "견적", "계약", "긴급" 같은 핵심 단어가 잡히면 격리하지 않고 즉시 알림을 보내요. 단, "무료견적"·"특가" 같은 광고 냄새 키워드가 함께 있으면 무효가 됩니다.
광고·영업 패턴 — "매출을 올려", "마케팅 대행" 같은 영업 메일과 광고성 발신자는 정리 라벨로 격리.
분류 격리 — 협찬·제휴 → 뉴스레터 → 금융(영수증·청구서) → 일반 정리 순서로 검사해서 해당 라벨로 이동.
아무것도 안 걸리면 — 받은편지함에 그대로 둡니다.

그리고 안심되는 안전장치가 있어요. gmail-butler 는 메일을 영구 삭제하지 않습니다. 받은편지함에서 빼서 라벨(폴더처럼 쓰는 꼬리표)을 붙일 뿐이에요. 언제든 라벨을 열어 확인할 수 있어요. 실행 전에 --dry-run(드라이런, 실제로 옮기지 않고 결과만 미리 보는 모드)으로 확인할 수도 있고, 구글에 요청하는 권한도 gmail.modify(라벨 수정) 딱 하나뿐이라 영구 삭제 권한 자체를 갖고 있지 않아요.

우리는 이렇게 쓰고 있어요

소개용 데모가 아니라 실제 운영 기록을 보여드릴게요.

제게는 에르메스라는 개인 AI 에이전트(제 일을 대신해 주는 AI 비서)가 있어요. 에르메스가 이 엔진을 cron 잡(크론 잡, 정해진 시간마다 프로그램을 자동 실행하는 예약 기능) 으로 등록해서 30분마다 돌립니다. 2026년 6월 1일에 등록했고, 오늘(7월 6일)까지 1,551회 실행됐어요. 실제 집계된 숫자입니다. 한 달 넘게, 밤이든 주말이든 30분마다 한 번도 안 빼먹고 메일함을 청소한 거죠.

결과 보고는 텔레그램으로 받아요. 이 방식이 마음에 드는데요 — 중요한 메일이 오면 "사장님, 이건 보셔야 합니다" 하고 알려주고, 나머지는 그냥 "정리했습니다" 한 줄로 끝나요. 제가 메일함을 들여다볼 이유 자체가 사라진 거예요.

그 결과가 이 화면이에요. 제 받은편지함의 실제 상태를 그대로 옮긴 화면입니다. (거래처와 개인정보 보호를 위해 발신자 이름과 내용 일부는 가상으로 바꿨어요. 라벨 구성과 건수, 메일 종류는 실제 그대로입니다.)

자동화 후의 Gmail 받은편지함 재현 화면 — 기본 탭에 안 읽은 메일이 없고, 왼쪽에 금융·뉴스레터·정리 라벨 3개, 정리 라벨에 23건이 격리되어 쌓여 있는 상태. 개인정보 보호를 위해 발신자·내용은 가상 텍스트로 치환

이 화면이 왜 이렇게 생겼는지 뜯어볼게요.

기본 탭(업무 메일이 오는 곳)에 안 읽은 메일이 0통이에요. 중요한 메일은 텔레그램 알림이 올 때 바로 확인하니까, "안 읽음"이 쌓일 틈이 없어요. 왼쪽 받은편지함 옆 숫자는 프로모션·업데이트 같은 다른 탭 메일까지 합쳐진 거예요.
왼쪽에 라벨이 3개 보여요 — 금융, 뉴스레터, 정리. 집사가 서랍 3개를 만들어서 종류별로 넣어둔 거예요.
정리 라벨에 23건이 쌓여 있죠. 광고와 영업 메일이 격리된 곳이에요. 시간 날 때 한 번 훑어보고, 전체선택 → 삭제 클릭 한 번이면 끝납니다. 지우기 전에 눈으로 확인할 수 있으니 마음이 편해요.

숫자로 정리하면 이렇습니다.

	도입 전	도입 후
아침 메일 정리	매일 약 30분 (체감)	0분
중요 메일 확인	수십 통 사이에서 눈으로 골라냄	텔레그램 알림 올 때만
광고·뉴스레터 처리	한 통씩 열어보고 삭제	라벨에 모였다가 한 번에 삭제

하루 30분이면 1년에 약 180시간이에요. 8시간 근무일로 환산하면 22일이 넘는 시간이죠. (체감치 기준 환산이지만, 한 달 가까운 근무일을 메일 고르는 데 쓰고 있었다는 얘기예요.)

솔직한 고백도 하나 할게요. 처음 돌렸을 때는 중요한 견적 메일까지 정리함에 들어갔어요. 광고 키워드에 걸린 거죠. 순간 아찔했는데, 해결은 어렵지 않았어요. must_see 키워드에 "견적"·"계약"·"발주"를 넣고, 주요 거래처 주소를 화이트리스트에 올렸더니 그 뒤로는 한 번도 놓친 적이 없습니다. 규칙은 지금도 쓰면서 계속 업데이트해요. "왜 이 메일이 정리됐지?" 싶으면 어떤 키워드에 걸렸는지 답이 명확하니까(AI처럼 "그냥 그렇게 판단했어요"가 아니라), 규칙 한 줄 고치면 끝이거든요.

한번 써볼까요?

설치는 크게 3단계예요. 코드를 몰라도 따라올 수 있게 순서대로 안내할게요. 먼저 저장소를 내려받고 필요한 라이브러리를 설치합니다. (파이썬 3.8 이상이 필요해요.)

# 저장소 내려받기
git clone https://github.com/digiwood7/gmail-butler.git
cd gmail-butler

# 필요한 라이브러리 설치 (구글 공식 SDK 3개뿐이에요)
pip install -r requirements.txt

1단계 — 구글에 "허락증" 만들기. 이 도구가 내 Gmail 을 만질 수 있게 허락하는 자격증명 파일이 필요해요. 구글 클라우드 콘솔에서 새 프로젝트를 만들고 → Gmail API 를 사용 설정하고 → OAuth(오어스, 비밀번호를 알려주지 않고 안전하게 권한만 넘기는 표준 방식) 동의 화면을 만들고 → 데스크톱 앱 유형의 OAuth 클라이언트 ID 를 만들어 JSON 을 내려받은 뒤, 그 파일을 client_secret.json 이라는 이름으로 gmail-butler 폴더에 두면 됩니다. 클릭 순서 하나하나는 저장소 README에 스크린샷 없이도 따라갈 수 있게 적어뒀어요. (한 가지만 미리 — 동의 화면의 테스트 사용자에 본인 Gmail 주소를 꼭 추가해야 인증이 됩니다.)

2단계 — 브라우저로 인증하기.

# 브라우저가 열리면 청소할 구글 계정으로 로그인하고 동의
python setup_auth.py

계정을 여러 개 쓰신다면 이름을 붙여 한 번씩 더 실행하면 돼요.

python setup_auth.py work       # → data/token_work.json
python setup_auth.py personal   # → data/token_personal.json

3단계 — 규칙 만들고 실행. 예시 파일을 복사한 다음, 키워드와 화이트리스트를 내 메일함 사정에 맞게 고칩니다.

# 예시 규칙/설정 파일을 내 것으로 복사
cp rules.example.json  rules.json
cp config.example.json config.json

그리고 꼭 미리보기부터 하세요. 실제로 옮기지 않고 무엇이 어떻게 분류될지만 보여줍니다.

# 읽기 전용 미리보기 — 라벨도 안 만들고 메일도 안 옮겨요
python cleanup.py --dry-run

결과가 마음에 들면 진짜로 실행합니다.

python cleanup.py

주기적으로 자동 실행하고 싶으면 가장 간단한 건 상주 모드예요. 30분마다 스스로 반복합니다.

# 30분마다 반복 실행 (터미널을 켜두면 돼요)
python cleanup.py --loop 30

cron·launchd(맥)·작업 스케줄러(윈도우)로 등록하는 방법도 README에 다 적어뒀습니다.

클로드 코드 터미널에서는 이렇게

솔직히 1단계(구글 클라우드 설정)가 처음 하는 분께는 제일 낯설 거예요. 그러니 클로드 코드에게 손을 잡아 달라고 부탁합시다. 클로드 코드 대화창에 아래를 그대로 붙여 넣으세요. (이건 명령어가 아니라 AI에게 거는 부탁이라 ! 를 붙이지 않아요.)

이 저장소를 내 컴퓨터에 설치해줘: https://github.com/digiwood7/gmail-butler
그다음 README의 1단계(구글 클라우드에서 OAuth 클라이언트 만들기)를 나랑 같이 진행해줘.
나는 코드를 전혀 모르니까, 브라우저에서 어디를 눌러야 하는지 한 단계씩 알려줘.
client_secret.json 이 준비되면 python setup_auth.py 로 인증하고,
rules.example.json 을 rules.json 으로 복사하는 것까지 해줘.

클로드가 저장소를 내려받고, 구글 클라우드 화면에서 뭘 눌러야 하는지 차근차근 안내해 줍니다. 인증까지 끝났으면 이제 미리보기를 돌려볼 차례예요.

클로드 코드 대화창에서 ! 를 맨 앞에 붙이면 터미널 명령어를 바로 실행할 수 있어요.

# 실제로 옮기기 전에, 무엇이 어떻게 분류될지 미리보기 (앞에 ! 붙임)
! python cleanup.py --dry-run

미리보기 결과를 보고 "어, 이 메일은 정리되면 안 되는데" 싶은 게 있으면, 클로드에게 한국어로 말하면 됩니다. "거래처 ○○ 주소를 화이트리스트에 추가해줘" 하면 rules.json 을 대신 고쳐줘요. 결과가 마음에 들면 진짜로 실행합니다.

# 진짜 실행 — 라벨을 만들고 메일을 격리해요 (앞에 ! 붙임)
! python cleanup.py

마지막으로, 저처럼 30분마다 자동으로 돌게 만들고 싶으면 이렇게 부탁하세요.

결과가 마음에 들어. 이 폴더의 cleanup.py 가 30분마다 자동 실행되게
내 컴퓨터의 스케줄(cron)에 등록해줘. 로그는 data/cron.log 에 남겨줘.

여기까지 하면 여러분의 메일함에도 24시간 쉬지 않는 집사가 한 명 생긴 거예요.

이런 분께 추천해요

gmail-butler 는 "메일함은 넘치는데, 놓치면 안 되는 메일이 섞여 있는" 분들을 위한 도구예요. 특히 이런 세 분께 권해드려요.

견적 문의를 메일로 받는 제조업·소상공인 사장님 — 저와 똑같은 상황이죠. 광고 수십 통 사이에서 견적 요청과 관공서 공문을 눈으로 골라내고 계시다면, must_see 키워드에 "견적"·"발주"·"공문"을 넣는 것만으로 그 일이 사라져요. 놓치면 매출인 메일일수록 사람 눈보다 규칙이 정확합니다.
뉴스레터와 구독 메일에 파묻힌 1인 대표 — 공부하려고 구독한 뉴스레터가 정작 업무 메일을 덮어버리는 분이요. 뉴스레터는 전용 라벨에 모아뒀다가 주말에 몰아 읽고, 받은편지함은 업무 메일만 남길 수 있어요.
메일 정리를 직원에게 못 맡기는 소규모 팀 — 대표 메일함에는 계약·급여·거래처 정보가 다 들어 있어서 남에게 열어주기 어렵잖아요. gmail-butler 는 메일 본문을 외부로 보내지 않고 내 컴퓨터 안에서만 처리하니까, 사람 대신 맡겨도 마음이 편한 집사예요.

반대로, 발신자와 키워드로 구분이 안 되는 미묘한 판단(예: "이 제안 메일이 진짜 기회인지")까지 자동으로 하고 싶은 분께는 맞지 않아요. 그건 규칙이 아니라 사람(또는 AI)의 일이고, 이 도구는 그 판단 이전의 잡일을 없애주는 물건입니다.

참고 링크

공식 GitHub: digiwood7/gmail-butler (라이선스 MIT)
Gmail API 공식 문서: developers.google.com/gmail/api/guides
구글 클라우드 콘솔 (OAuth 클라이언트 만드는 곳): console.cloud.google.com

▸개정 이력1건

v12026-07-06초판

이 글이 도움이 되었나요?

이건 뭐예요?​

우리는 이렇게 쓰고 있어요​

한번 써볼까요?​

클로드 코드 터미널에서는 이렇게​

이런 분께 추천해요​

참고 링크​