gmail

name	gmail
description	gogcli를 사용하여 Gmail 메일을 검색, 조회, 발송하는 skill. "메일 검색해줘", "이메일 보내줘", "gmail search", "메일 확인해줘", "최근 메일", "신규 메일", "메일 답장", "gmail send", "메일 보내줘", "안 읽은 메일" 등 Gmail 관련 요청에 트리거된다.

Gmail — gogcli 기반 메일 검색/조회/발송

gogcli(gog) CLI를 사용하여 Gmail 메일을 검색, 조회, 발송한다.

디렉토리 구조

gmail/
├── SKILL.md
└── references/
    └── gog-gmail-commands.md   # 주요 명령어 레퍼런스

스크립트 없이 gog CLI를 직접 실행한다.

플로우

1. gogcli 설치 확인

which gog

명령이 실패하면 사용자에게 설치를 안내한다:

gogcli 설치 안내

brew install gogcli

설치 완료 후 다시 시도해주세요.

설치가 확인되면 다음 단계로 진행한다.

2. 인증 확인

gog auth list

계정이 없으면 OAuth 설정을 안내한다:

Gmail 인증 설정 가이드

1. Google Cloud Console에서 프로젝트 생성
2. Gmail API 활성화
3. OAuth 동의 화면 설정 → 테스트 사용자 추가
4. OAuth 클라이언트 생성 → "Desktop app" → JSON 다운로드
5. 터미널에서 아래 명령 실행:

gog auth credentials ~/Downloads/client_secret_....json
gog auth add <[e-mail]> --services gmail

브라우저가 열리면 Google 계정으로 로그인하여 권한을 허용해주세요.

인증이 확인되면 GOG_ACCOUNT 환경변수 또는 --account 플래그로 계정을 지정한다.

계정 선택 규칙

• 등록된 계정이 1개뿐이면 해당 계정을 그대로 사용한다.
• 등록된 계정이 여러 개인 경우:
  • 사용자가 계정을 명시했거나, 요청 맥락에서 어떤 계정을 써야 하는지 파악 가능하면 해당 계정을 사용한다.
  • 어떤 계정을 써야 할지 파악할 수 없으면 AskUserQuestion으로 사용자에게 어떤 계정을 사용할지 물어본다.

3. 요청 분류 및 실행

사용자 요청을 아래 중 하나로 분류하여 실행한다.

메일 검색

gog gmail search '<Gmail 검색 쿼리>' --max <N> --json

출력 스키마 — envelope 객체로 감싸져 있으며, 각 thread의 필드는 아래가 전부다. snippet·to·body 필드는 없다:

{
  "nextPageToken": "",
  "threads": [
    { "id": "...", "date": "YYYY-MM-DD HH:MM", "from": "...",
      "subject": "...", "labels": ["INBOX", ...], "messageCount": 2 }
  ]
}

자주 쓰는 검색 쿼리:

• 최근 N일: newer_than:7d
• 안 읽은 메일: is:unread
• 특정 발신자: from:[e-mail]
• 첨부파일 있는 메일: has:attachment
• 복합 조건: from:[e-mail] newer_than:3d is:unread

메시지 수준 검색 (본문 포함)

gog gmail messages search '<query>' --max <N> --include-body --json

출력 스키마 — 역시 envelope 객체다. snippet 필드는 없고, 본문은 --include-body 플래그를 붙여야 body로 들어온다:

{
  "nextPageToken": "...",
  "messages": [
    { "id": "...", "threadId": "...", "date": "YYYY-MM-DD HH:MM",
      "from": "...", "subject": "...", "labels": [...],
      "body": "..." }
  ]
}

스레드 조회

gog gmail thread get <threadId> --json

메시지 조회

gog gmail get <messageId> --json

메일 발송

gog gmail send --to <수신자> --subject "<제목>" --body "<본문>"

CC/BCC 추가:

gog gmail send --to <수신자> --cc <참조> --bcc <숨은참조> --subject "<제목>" --body "<본문>"

HTML 본문:

gog gmail send --to <수신자> --subject "<제목>" --body "Plain fallback" --body-html "<p>HTML 본문</p>"

답장

gog gmail send --reply-to-message-id <messageId> --quote --to <수신자> --subject "Re: <원제목>" --body "<답장 내용>"

라벨 조회

gog gmail labels list --json

첨부파일 다운로드

gog gmail thread get <threadId> --download --out-dir <다운로드경로>

초안 관리

# 초안 목록
gog gmail drafts list --json

# 초안 생성
gog gmail drafts create --to <수신자> --subject "<제목>" --body "<본문>"

# 초안 발송
gog gmail drafts send <draftId>

4. 결과 출력

JSON 결과를 파싱하여 사용자에게 읽기 좋게 정리한다:

• 검색 결과: 발신자, 제목, 날짜(+ 필요 시 labels/messageCount)를 테이블 형태로. 본문 미리보기가 필요하면 messages search --include-body로 재조회한다 (search 결과에 snippet 필드는 없음)
• 메시지 조회: 헤더(From/To/Subject/Date) + 본문
• 발송 결과: 성공 여부와 메시지 ID

알림 필터링 (Discord 등 외부 채널로 알릴 때)

메일을 외부 채널(Discord 등)로 알리기 전에, 반드시 아래 스크립트를 실행하여 판정한다:

python3 .claude/skills/gmail/scripts/check_filter.py \
  --from "<발신자>" \
  --subject "<제목>"

출력	exit code	의미
always_inbox	0	반드시 알림 전송
ignore	1	알림 건너뜀
notify	2	기본 동작 (알림 전송)

필터 규칙 추가/수정은 data/filter-prefs.json에서 한다.

Invariants

• 조회 명령에는 항상 --json 플래그를 붙여 파싱 가능한 출력을 얻는다
• 메일 발송은 실행 전 반드시 사용자에게 수신자, 제목, 본문을 확인받는다
• gogcli 미설치 또는 미인증 상태에서는 명령을 실행하지 않고 설정 안내를 진행한다
• OAuth 자격증명은 gogcli 자체 keyring에 저장된다 — skill 디렉토리에 저장하지 않는다
• GOG_ACCOUNT 환경변수가 설정되어 있으면 우선 사용한다

jq 파싱 함정 (중요)

gog gmail search / messages search의 --json 출력은 항상 envelope 객체({threads: [...]} 또는 {messages: [...]})다. 과거에 아래 실수들이 반복되어 전부 에러로 터졌다:

• .snippet 필드를 가정 → 존재하지 않음. 본문이 필요하면 gog gmail messages search --include-body 또는 gog gmail thread get <id>.
• top-level을 배열로 가정(jq 'map(...)', jq 'length') → envelope 객체이므로 실패하거나 엉뚱한 값(객체 key 수)을 돌려준다. 먼저 .threads / .messages로 드릴다운해야 한다.
• jq '.threads | length, (.threads | map(.id))' 같이 쓰면 |보다 , 우선순위가 낮아 전체가 .threads | (length, (.threads | map(.id)))로 파싱되고 두 번째 .threads가 배열에 적용돼 터진다. 첫 드릴다운은 한 번만, 혹은 envelope을 유지한 채 두 표현식을 쓰자.

안전 패턴:

# 안전: 한 번만 드릴다운
... --json | jq '.threads | map({id, from, subject, date})'

# envelope을 그대로 유지하며 두 값 뽑기
... --json | jq '{count: (.threads|length), ids: [.threads[].id]}'

# envelope이 귀찮으면 --results-only 로 배열만 받기
gog gmail search '...' --json --results-only | jq 'map({id, from, subject})'

주의사항

• Gmail 검색 쿼리는 Gmail 검색 문법을 따른다 (Google 검색 연산자).
• 대량 조회 시 --max 플래그로 결과 수를 제한한다.
• 발송 시 --track 옵션으로 읽음 추적이 가능하나, 사전 설정이 필요하다.