| 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 인증 설정 가이드
- Google Cloud Console에서 프로젝트 생성
- Gmail API 활성화
- OAuth 동의 화면 설정 → 테스트 사용자 추가
- OAuth 클라이언트 생성 → "Desktop app" → JSON 다운로드
- 터미널에서 아래 명령 실행:
gog auth credentials ~/Downloads/client_secret_....json
gog auth add <your-email@gmail.com> --services gmail
브라우저가 열리면 Google 계정으로 로그인하여 권한을 허용해주세요.
인증이 확인되면 GOG_ACCOUNT 환경변수 또는 --account 플래그로 계정을 지정한다.
계정 선택 규칙
- 등록된 계정이 1개뿐이면 해당 계정을 그대로 사용한다.
- 등록된 계정이 여러 개인 경우:
- 사용자가 계정을 명시했거나, 요청 맥락에서 어떤 계정을 써야 하는지 파악 가능하면 해당 계정을 사용한다.
- 어떤 계정을 써야 할지 파악할 수 없으면 AskUserQuestion으로 사용자에게 어떤 계정을 사용할지 물어본다.
3. 요청 분류 및 실행
사용자 요청을 아래 중 하나로 분류하여 실행한다.
메일 검색
gog gmail search '<Gmail 검색 쿼리>' --max <N> --json
자주 쓰는 검색 쿼리:
- 최근 N일:
newer_than:7d
- 안 읽은 메일:
is:unread
- 특정 발신자:
from:someone@example.com
- 첨부파일 있는 메일:
has:attachment
- 복합 조건:
from:boss@example.com newer_than:3d is:unread
메시지 수준 검색 (본문 포함)
gog gmail messages search '<query>' --max <N> --include-body --json
스레드 조회
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 결과를 파싱하여 사용자에게 읽기 좋게 정리한다:
- 검색 결과: 발신자, 제목, 날짜, 스니펫을 테이블 형태로
- 메시지 조회: 헤더(From/To/Subject/Date) + 본문
- 발송 결과: 성공 여부와 메시지 ID
Invariants
- 조회 명령에는 항상
--json 플래그를 붙여 파싱 가능한 출력을 얻는다
- 메일 발송은 실행 전 반드시 사용자에게 수신자, 제목, 본문을 확인받는다
- gogcli 미설치 또는 미인증 상태에서는 명령을 실행하지 않고 설정 안내를 진행한다
- OAuth 자격증명은 gogcli 자체 keyring에 저장된다 — skill 디렉토리에 저장하지 않는다
GOG_ACCOUNT 환경변수가 설정되어 있으면 우선 사용한다
주의사항
- Gmail 검색 쿼리는 Gmail 검색 문법을 따른다 (Google 검색 연산자).
- 대량 조회 시
--max 플래그로 결과 수를 제한한다.
- 발송 시
--track 옵션으로 읽음 추적이 가능하나, 사전 설정이 필요하다.
