웹사이트: zacbowling.com

Python 3.12 이상
uv (권장) 또는 pip
Gmail API 자격 증명 (credentials)
반드시 본인만의 OAuth 앱을 생성해야 합니다 (아래 Gmail API 설정 참조)
LLM API 키 (Gemini, Anthropic, 또는 OpenAI)

# 저장소 복제 (Clone the repository)
git clone https://github.com/yourusername/gmail-ai-unsub.git
cd gmail-ai-unsub
...

pip install gmail-ai-unsub

중요: 이 도구의 OAuth 앱은 아직 Google의 검증을 받지 않았으므로, 모든 사용자는 도구를 사용하기 위해 반드시 자신만의 OAuth 자격 증명 (credentials)을 생성해야 합니다. 이는 약 10분 정도 소요되는 일회성 설정입니다.

도구가 귀하의 Gmail 계정에 접근할 수 있도록 하기 위해, 아래 단계에 따라 본인만의 Google Cloud OAuth 앱을 생성하십시오.

Google Cloud Console로 이동
"프로젝트 선택 (Select a project)\
이름을 credentials.json으로 변경하십시오.

옵션 A: 설정 마법사 (setup wizard) 사용

credentials.json 파일을 다음의 설정 디렉토리 (config directory)에 배치하십시오:

기본 위치:

Linux: ~/.config/gmail-ai-unsub/

macOS: ~/Library/Application Support/gmail-ai-unsub/

Windows: %LOCALAPPDATA%\gmail-ai-unsub\gmail-ai-unsub\

gmail-unsub setup을 실행하고,

프롬프트가 나타나면 해당 경로를 지정하십시오.

옵션 B: 환경 변수 (environment variables) 사용 (개발용)

프로젝트 루트에 .env 파일을 생성하십시오:
GMAIL_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your-client-secret
실행 전 다음 명령어로 로드하십시오:
export $(cat .env | xargs)

옵션 C: config.toml에 지정

[gmail]
credentials_file = "/path/to/credentials.json"

테스트 모드 (Testing Mode): 귀하의 앱은 "테스트 (Testing)" 모드로 시작됩니다. 귀하가 추가한 테스트 사용자만 앱을 사용할 수 있습니다.

미인증 앱 경고 (Unverified App Warning): 사용자에게 "이 앱은 확인되지 않았습니다 (This app isn't verified)"라는 메시지가 표시됩니다. 이는 미인증 앱의 경우 정상적인 현상입니다.

운영 환경 사용 (Production Use): 경고를 제거하려면 다음이 필요합니다:

앱 인증 (app verification) 완료 (도메인, 개인정보 처리방침 등이 필요함)
Gmail 스코프 (scopes)의 경우, CASA 보안 평가 (security assessment)가 필요할 수 있습니다 (비용이 많이 듭니다)
자세한 내용은 docs/oauth-credentials.md를 참조하십시오.

속도 제한 (Rate Limits): 테스트 모드는 속도 제한이 더 낮습니다. 운영 환경을 위해서는 앱 인증을 고려하십시오.

"액세스 차단됨 (Access blocked)": 3단계에서 귀하 자신을 테스트 사용자로 추가했는지 확인하십시오.

"잘못된 클라이언트 (Invalid client)": 클라이언트 ID (Client ID)와 비밀번호 (Secret)를 정확하게 복사했는지 확인하십시오.

"리디렉션 URI 불일치 (Redirect URI mismatch)": 데스크톱 앱 (Desktop app) 유형은 http://localhost를 사용합니다.

이는 자동으로 작동해야 합니다.

더 자세한 내용은 docs/oauth-credentials.md를 참조하십시오.

귀하만의 OAuth 앱을 반드시 생성해야 합니다 - 이 도구의 앱은 아직 Google의 인증을 받지 않았습니다. 위의 Gmail API 설정 단계를 따라 다음을 수행하십시오:

Google Cloud 프로젝트 생성
Gmail API 활성화
OAuth 동의 화면 (OAuth consent screen) 구성
OAuth 자격 증명 (OAuth credentials) 생성
credentials.json 파일 다운로드

이는 약 10분이 소요되는 일회성 설정입니다.

설정 마법사를 실행하여 구성을 생성하십시오:

gmail-unsub setup

이 과정은 다음 단계들을 안내합니다:

LLM 제공업체 선택 (Gemini, Claude 또는 OpenAI)
모델 선택 및 설정 구성
Gmail OAuth 인증 설정 (credentials.json 지정)
레이블 (labels) 및 분류 프롬프트 (classification prompts) 사용자 정의

Gmail API 자격 증명 설정 (필수):

위의 Gmail API 설정 단계를 따르십시오
credentials.json 파일을 다운로드하십시오

설정 파일 생성:

cp config.example.toml ~/.gmail-ai-unsub/config.toml
# API 키와 선호 설정으로 config.toml을 편집하십시오

LLM API 키 설정:

export GOOGLE_API_KEY=your_gemini_api_key
# 또는 Anthropic의 경우:
# export ANTHROPIC_API_KEY=your_key

받은 편지함 스캔:

gmail-unsub scan --days 30

대화형 설정 마법사를 실행하십시오:

gmail-unsub setup

옵션:

--force
: 기존 설정 파일을 덮어씁니다

받은 편지함을 스캔하고 구독 해제를 위한 이메일에 레이블을 지정합니다:

옵션:

--days
: 스캔할 이메일의 일수 (기본값: 30)

--label
: config.toml 파일 경로

옵션:

--label
: 브라우저를 헤드리스 (headless) 모드로 실행

--config
: config.toml 파일 경로

gmail-unsub status

상세한 설정 옵션은 docs/configuration.md를 참조하십시오.

주요 설정 섹션:

[gmail]
: Gmail API 자격 증명

[llm]
: LLM 제공업체 및 모델 선택

[prompts]
: 이메일 분류를 위한 사용자 정의 가능 프롬프트

[labels]
: 브라우저 자동화 설정

스캔 단계 (Scanning Phase):

Gmail 받은 편지함에서 이메일을 가져옵니다
이메일 내용을 LLM에 보내 분류합니다
마케팅으로 식별된 이메일에 레이블을 지정합니다
복잡한 페이지를 위해 AI 비전 (AI vision)을 사용한 브라우저 자동화를 사용합니다
성공/실패 여부에 따라 레이블을 업데이트합니다

이러한 발신자의 경우, 다음 작업이 필요할 수 있습니다:

이메일을 스팸으로 표시 (Gmail이 이를 필터링하는 법을 학습하게 됩니다)

저희는 이러한 사례를 처리하기 위해 브라우저 자동화를 개선하는 작업을 활발히 진행하고 있습니다. 특정 발신자와 관련하여 문제가 발생하면 상세 내용을 포함하여 이슈(issue)를 생성해 주세요.

Google Gemini:gemini-3-pro-preview

(최신, 2025년 11월, thinking_level=high 또는 low와 함께 사용)

(속도 요구 사항에 따라 선택) gemini-2.5-computer-use

(브라우저 자동화용, 다만 gemini-3-pro가 더 나은 경우가 많음) - 참고: Gemini 2.0 모델은 권장되지 않음

Anthropic Claude:claude-4-5-sonnet-20250514

(최신 Claude 4.5 시리즈) claude-4-opus-20250514

(가장 뛰어난 성능)

OpenAI:gpt-5

(최신 플래그십, 2025년 8월, 박사(PhD) 수준의 성능) gpt-5-mini

(더 빠른 변형 모델) gpt-4.1

(개선된 코딩 능력, 1M 토큰 컨텍스트) o4-mini

(비전 기능이 포함된 추론 모델) o3

(설정 가능한 분석 깊이를 가진 추론 모델)

API 접근 권한이 있는 Gmail 계정
LLM API 키 (Gemini, Anthropic 또는 OpenAI)
인터넷 연결
모든 API 키와 인증 정보는 로컬에 저장됩니다.
Gmail API는 PKCE를 사용하는 OAuth2 인증을 사용합니다.
선택한 LLM 제공업체를 제외하고는 제3자에게 데이터가 전송되지 않습니다.
모든 처리는 사용자의 기기에서 이루어집니다.
OAuth 인증 정보 (OAuth Credentials): 이 도구는 편의를 위해 임베디드된 OAuth 인증 정보를 포함하고 있습니다. 프로덕션 환경에서 사용하려면 자체 OAuth 앱을 생성하는 것을 고려하십시오 (Developer Setup 참조). 네이티브/데스크톱 앱의 경우, client_secret은 공개 메타데이터로 취급됩니다 - 보안은 PKCE와 사용자 동의를 통해 확보됩니다.

MIT License - 자세한 내용은 LICENSE 파일을 참조하십시오.

기여(Contributions)를 환영합니다!

개발 환경 설정은 Developer Setup을 참조하십시오.
PyPI 배포는 docs/releasing.md를 참조하십시오.
PR(Pull Request)을 제출하기 전에 다음 명령어를 실행해 주세요:
ruff check --fix .

및
ruff format .

이슈(Issues), 질문 또는 기능 요청이 있는 경우 GitHub에 이슈를 생성해 주세요.

사용된 기술:

LLM 통합을 위한 LangChain
브라우저 자동화를 위한 browser-use
이메일 접근을 위한 Gmail API

zbowling/gmail-ai-unsub

요약

핵심 포인트

기본 위치:

Linux: ~/.config/gmail-ai-unsub/

macOS: ~/Library/Application Support/gmail-ai-unsub/

Windows: %LOCALAPPDATA%\gmail-ai-unsub\gmail-ai-unsub\

댓글

기본 위치:

Linux: ~/.config/gmail-ai-unsub/

macOS: ~/Library/Application Support/gmail-ai-unsub/

Windows: %LOCALAPPDATA%\gmail-ai-unsub\gmail-ai-unsub\