{"id":47516113,"url":"https://github.com/c4pt0r/gmailtail","last_synced_at":"2026-04-01T07:00:41.811Z","repository":{"id":302356904,"uuid":"1012167700","full_name":"c4pt0r/gmailtail","owner":"c4pt0r","description":"tail -f your gmail","archived":false,"fork":false,"pushed_at":"2025-11-21T09:03:03.000Z","size":150,"stargazers_count":428,"open_issues_count":1,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-11-21T11:07:15.026Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/c4pt0r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-01T23:34:31.000Z","updated_at":"2025-11-21T09:03:07.000Z","dependencies_parsed_at":"2025-07-02T00:38:53.161Z","dependency_job_id":null,"html_url":"https://github.com/c4pt0r/gmailtail","commit_stats":null,"previous_names":["c4pt0r/gmailtail"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/c4pt0r/gmailtail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4pt0r%2Fgmailtail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4pt0r%2Fgmailtail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4pt0r%2Fgmailtail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4pt0r%2Fgmailtail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/c4pt0r","download_url":"https://codeload.github.com/c4pt0r/gmailtail/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/c4pt0r%2Fgmailtail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31269176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T06:57:45.811Z","status":"ssl_error","status_checked_at":"2026-04-01T06:57:42.389Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-27T13:00:30.245Z","updated_at":"2026-04-01T07:00:41.797Z","avatar_url":"https://github.com/c4pt0r.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"email\"\u003e\u003c/a\u003eEmail"],"sub_categories":[],"readme":"# gmailtail\n\nA command-line tool to monitor Gmail messages and output them as JSON, designed for automation, monitoring, and integration with other tools.\n\nWhy: [My Blog](https://me.0xffff.me/gmailtail.html)\n\n## Features\n\n-  **Real-time monitoring** - Continuous monitoring of new emails with `--tail` mode\n-  **Flexible filtering** - Filter by sender, subject, labels, attachments, and more\n-  **Checkpoint support** - Resume monitoring from where you left off\n-  **Multiple output formats** - JSON, JSON Lines, and compact formats\n-  **Configuration files** - YAML configuration for complex setups\n-  **Gmail search syntax** - Full support for Gmail's powerful search queries\n-  **Easy authentication** - Support for OAuth2 and service accounts\n-  **Interactive REPL mode** - Interactive shell for exploring and querying emails\n\n## Quick Start\n\n1. **Install using uv (recommended):**\n   ```bash\n   # Install uv if you haven't already\n   curl -LsSf https://astral.sh/uv/install.sh | sh\n   \n   # Clone and setup the project\n   git clone https://github.com/c4pt0r/gmailtail.git\n   cd gmailtail\n   uv sync\n   ```\n\n2. **Set up Google API credentials:**\n   - Go to [Google Cloud Console](https://console.cloud.google.com/)\n   - Create a new project or select an existing one\n   - Enable the Gmail API\n   - Create credentials (OAuth 2.0 Client ID for desktop applications)\n   - Download the credentials JSON file\n\n3. **Run gmailtail:**\n   ```bash\n   # Start in tail mode (continuous monitoring)\n   uv run gmailtail --credentials credentials.json --tail\n   \n   # Or start in interactive REPL mode\n   uv run gmailtail --credentials credentials.json --repl\n   ```\n\n## Installation\n\n### Using uv (recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/c4pt0r/gmailtail.git\ncd gmailtail\n\n# Install dependencies and create virtual environment\nuv sync\n\n# Install in development mode\nuv pip install -e .\n```\n\n\n## Usage Examples\n\n### Basic monitoring\n```bash\n# Monitor all new emails\ngmailtail --tail\n\n# Monitor emails from specific sender\ngmailtail --from \"noreply@github.com\" --tail\n\n# Monitor with Gmail search query\ngmailtail --query \"subject:alert OR subject:error\" --tail\n```\n\n### Filtering options\n```bash\n# Monitor unread emails only\ngmailtail --unread-only --tail\n\n# Monitor emails with attachments\ngmailtail --has-attachment --include-attachments --tail\n\n# Monitor specific labels\ngmailtail --label important --label work --tail\n\n# Monitor since specific date\ngmailtail --since \"2025-01-01T00:00:00Z\" --tail\n```\n\n### Output formats\n```bash\n# Pretty JSON output\ngmailtail --format json --pretty --tail\n\n# JSON Lines format (one JSON per line)\ngmailtail --format json-lines --tail\n\n# Compact format\ngmailtail --format compact --tail\n\n# Include email body\ngmailtail --include-body --max-body-length 500 --tail\n\n# Custom fields only\ngmailtail --fields \"id,subject,from,timestamp\" --tail\n```\n\n### Checkpoint management\n```bash\n# Resume from last checkpoint\ngmailtail --resume --tail\n\n# Reset checkpoint and start fresh\ngmailtail --reset-checkpoint --tail\n\n# Custom checkpoint file\ngmailtail --checkpoint-file ./my-checkpoint --tail\n```\n\n### Configuration file\n```bash\n# Use configuration file\ngmailtail --config-file gmailtail.yaml\n\n# Example configuration file\ncp gmailtail.yaml.example gmailtail.yaml\n# Edit gmailtail.yaml as needed\ngmailtail --config-file gmailtail.yaml\n```\n\n### Advanced usage with jq\n\n```bash\n# Extract only sender email and subject\ngmailtail --format json-lines --tail | jq -r '.from.email + \": \" + .subject'\n\n# Filter emails by specific sender and get only timestamps\ngmailtail --format json-lines --tail | jq -r 'select(.from.email == \"noreply@github.com\") | .timestamp'\n\n# Count emails by sender\ngmailtail --format json-lines --once | jq -r '.from.email' | sort | uniq -c | sort -nr\n\n# Get all unique labels across emails\ngmailtail --format json-lines --once | jq -r '.labels[]?' | sort | uniq\n\n# Extract emails with attachments and show attachment info\ngmailtail --format json-lines --include-attachments --tail | jq 'select(.attachments | length \u003e 0) | {subject, from: .from.email, attachments: [.attachments[].filename]}'\n\n# Monitor for urgent emails and send desktop notifications (macOS)\ngmailtail --query \"label:urgent OR subject:urgent\" --format json-lines --tail | jq -r '.subject' | while read subject; do osascript -e \"display notification \\\"$subject\\\" with title \\\"Urgent Email\\\"\"; done\n\n# Extract email body text and save to files\ngmailtail --include-body --format json-lines --once | jq -r '\"\\(.id).txt|\\(.body // .snippet)\"' | while IFS='|' read filename content; do echo \"$content\" \u003e \"$filename\"; done\n\n# Monitor GitHub notifications and extract PR/issue numbers\ngmailtail --from \"notifications@github.com\" --format json-lines --tail | jq -r 'select(.subject | test(\"Pull Request|Issue\")) | .subject | capture(\".*#(?\u003cnumber\u003e[0-9]+).*\") | .number'\n\n# Create a summary of daily email activity\ngmailtail --since \"$(date -d 'today' '+%Y-%m-%dT00:00:00Z')\" --format json-lines --once | jq -r '[group_by(.from.email) | .[] | {sender: .[0].from.email, count: length}] | sort_by(.count) | reverse'\n\n# Monitor for emails with specific keywords in body and alert\ngmailtail --include-body --format json-lines --tail | jq -r 'select(.body | test(\"error|fail|alert\"; \"i\")) | \"ALERT: \\(.from.email) - \\(.subject)\"'\n\n# Extract and format meeting invitations\ngmailtail --query \"has:attachment filename:ics\" --include-attachments --format json-lines --tail | jq '{meeting: .subject, organizer: .from.email, time: .timestamp, location: (.body | capture(\"Location:.*(?\u003cloc\u003e.*)\")? | .loc // \"N/A\")}'\n```\n\n## Interactive REPL Mode\n\nThe REPL (Read-Eval-Print Loop) mode provides an interactive shell for exploring and querying your Gmail account. This is perfect for ad-hoc email searches, debugging filters, and exploring your email data.\n\n### Starting REPL Mode\n\n```bash\n# Start REPL with OAuth2 credentials\ngmailtail --credentials credentials.json --repl\n\n# Start REPL with configuration file\ngmailtail --config-file gmailtail.yaml --repl\n```\n\n### REPL Commands\n\nOnce in REPL mode, you can use these commands:\n\n#### Basic Email Operations\n```\n# List emails from current label (default: 10 emails)\ngmailtail\u003e ls\n\n# List 20 emails from current label\ngmailtail\u003e ls 20\n\n# List emails from specific label\ngmailtail\u003e ls INBOX\n\n# List 15 emails from specific label\ngmailtail\u003e ls work 15\n\n# List only unread emails (new improved syntax)\ngmailtail\u003e ls --unread\n\n# List 5 unread emails from specific label\ngmailtail\u003e ls --unread important 5\n\n# Show recent emails from INBOX (alias for ls)\ngmailtail\u003e tail\n\n# Show 10 recent emails from a specific label\ngmailtail\u003e tail work 10\n\n# Show unread emails from INBOX\ngmailtail\u003e unread\n\n# Show 5 unread emails from a specific label\ngmailtail\u003e unread important 5\n\n# Execute a Gmail search query\ngmailtail\u003e query from:noreply@github.com subject:pull\n```\n\n#### The ls Command (Enhanced Email Listing)\n\nThe `ls` command is the primary way to list emails in REPL mode. It supports flexible syntax and improved unread email handling:\n\n```\n# Basic usage\nls                        # List 10 emails from current label\nls 20                     # List 20 emails from current label\n\n# Specify label and limit\nls INBOX                  # List 10 emails from INBOX\nls work 15                # List 15 emails from work label\nls important 5            # List 5 emails from important label\n\n# Unread emails (new improved syntax)\nls --unread               # List unread emails from current label\nls -u                     # Short form for --unread\nls --unread 20            # List 20 unread emails from current label\nls --unread INBOX         # List unread emails from INBOX  \nls --unread work 10       # List 10 unread emails from work label\n\n# Handle numeric labels (use quotes)\nls \"123\"                  # List emails from label named \"123\"\nls \"123\" 5                # List 5 emails from label \"123\"\n\n# Mixed arguments (intelligent parsing)\nls 15 work                # List 15 emails from work (number first)\nls work 15                # List 15 emails from work (label first)\n```\n\n**Note**: The `ls` command intelligently parses arguments based on their type (numeric vs text), making it more flexible than the original implementation.\n\n#### Account Information\n```\n# Show your Gmail profile info\ngmailtail\u003e profile\n\n# List all available labels\ngmailtail\u003e labels\n\n# Show current configuration\ngmailtail\u003e config\n```\n\n#### Navigation\n```\n# Show help for all commands\ngmailtail\u003e help\n\n# Exit REPL\ngmailtail\u003e exit\n# or\ngmailtail\u003e quit\n# or press Ctrl+D\n```\n\n### REPL Examples\n\n```bash\n$ gmailtail --credentials credentials.json --repl\n\nWelcome to gmailtail REPL mode. Type 'help' for commands.\n\ngmailtail(INBOX)\u003e ls 3\n\n=== Showing 3 recent emails from INBOX ===\n\n 1. [18c5b2a4f2e1d8f0] [2025-01-15 10:30:25] GitHub \u003cnoreply@github.com\u003e     | New pull request assigned to you\n 2. [18c5b2a4f2e1d8f1] [2025-01-15 09:45:12] JIRA \u003cnoreply@jira.com\u003e        | Issue updated: Bug in login system  \n 3. [18c5b2a4f2e1d8f2] [2025-01-15 08:20:30] Slack \u003cnoreply@slack.com\u003e      | You have 5 new mentions\n\ngmailtail(INBOX)\u003e ls --unread important 2\n\n=== Found 2 unread emails in important ===\n\n 1. [18c5b2a4f2e1d8f3] [2025-01-15 11:00:00] Monitor \u003calerts@monitor.com\u003e   | Database connection alert\n 2. [18c5b2a4f2e1d8f4] [2025-01-15 10:30:00] System \u003csystem@server.com\u003e    | Server maintenance scheduled\n\ngmailtail(INBOX)\u003e ls work 5\n\n=== Showing 5 recent emails from work ===\n\n 1. [18c5b2a4f2e1d8f5] [2025-01-15 12:00:00] Boss \u003cboss@company.com\u003e        | Team meeting at 2 PM\n 2. [18c5b2a4f2e1d8f6] [2025-01-15 11:30:00] HR \u003chr@company.com\u003e           | New policy update\n 3. [18c5b2a4f2e1d8f7] [2025-01-15 11:15:00] Dev Team \u003cdev@company.com\u003e    | Code review required\n 4. [18c5b2a4f2e1d8f8] [2025-01-15 10:45:00] PM \u003cpm@company.com\u003e           | Sprint planning notes\n 5. [18c5b2a4f2e1d8f9] [2025-01-15 10:00:00] IT \u003cit@company.com\u003e           | System maintenance window\n\ngmailtail(INBOX)\u003e query subject:alert OR subject:error\n\n=== Found 2 messages ===\n\n 1. [18c5b2a4f2e1d8fa] [2025-01-15 11:15:00] Monitor \u003calerts@monitor.com\u003e   | Database connection alert\n 2. [18c5b2a4f2e1d8fb] [2025-01-15 10:00:00] System \u003csystem@server.com\u003e    | Error in backup process\n\ngmailtail(INBOX)\u003e use work\nSwitched to label: work\n\ngmailtail(work)\u003e ls\n\n=== Showing 10 recent emails from work ===\n\n 1. [18c5b2a4f2e1d8fc] [2025-01-15 12:30:00] Client \u003cclient@external.com\u003e   | Project update request\n 2. [18c5b2a4f2e1d8fd] [2025-01-15 12:15:00] Boss \u003cboss@company.com\u003e        | Budget approval needed\n ... (8 more emails)\n\ngmailtail(work)\u003e profile\nEmail: john.doe@example.com\nMessages Total: 15247\nThreads Total: 8932\nHistory ID: 1234567890\n\ngmailtail(work)\u003e labels\nAvailable labels:\n  INBOX (INBOX)\n  SENT (SENT)\n  DRAFT (DRAFT)\n  important (Label_1)\n  work (Label_2)\n  personal (Label_3)\n  \ngmailtail(work)\u003e exit\nGoodbye!\n```\n\n### REPL Output Format\n\nThe REPL uses a human-readable compact format that shows:\n- **Timestamp**: When the email was received\n- **Sender**: Name (if available) or email address\n- **Subject**: Email subject (truncated if too long)\n\nThis format is optimized for quick scanning and readability in the terminal.\n\n## Command Line Options\n\n### Authentication\n- `--credentials PATH` - OAuth2 credentials file path\n- `--auth-token PATH` - Service account authentication token file path\n- `--cached-auth-token PATH` - Cached authentication token file path (default: `~/.gmailtail/tokens`)\n\n### Filtering\n- `--query QUERY` - Gmail search query syntax\n- `--from EMAIL` - Filter by sender email\n- `--to EMAIL` - Filter by recipient email\n- `--subject PATTERN` - Filter by subject (regex supported)\n- `--label LABEL` - Filter by label (can be used multiple times)\n- `--has-attachment` - Only emails with attachments\n- `--unread-only` - Only unread emails\n- `--since DATETIME` - Start from specified time (ISO 8601)\n\n### Output\n- `--format FORMAT` - Output format: json, json-lines, compact\n- `--fields FIELDS` - Comma-separated list of fields to include\n- `--include-body` - Include email body in output\n- `--include-attachments` - Include attachment information\n- `--max-body-length N` - Maximum body length (default: 1000)\n- `--pretty` - Pretty-print JSON output\n\n### Monitoring\n- `--tail, -f` - Continuous monitoring (like `tail -f`)\n- `--repl` - Start interactive REPL mode\n- `--once` - Run once and exit\n- `--poll-interval N` - Polling interval in seconds (default: 30)\n- `--batch-size N` - Messages per batch (default: 10)\n- `--max-messages N` - Maximum messages to process\n\n### Checkpoint\n- `--checkpoint-file PATH` - Checkpoint file path\n- `--checkpoint-interval N` - Save interval in seconds (default: 60)\n- `--resume` - Resume from last checkpoint\n- `--reset-checkpoint` - Reset checkpoint\n\n### Other\n- `--verbose, -v` - Verbose output mode\n- `--quiet` - Quiet mode, only output email JSON\n- `--log-file PATH` - Log file path\n- `--config-file PATH` - Configuration file path\n- `--dry-run` - Simulate run without actual processing\n\n## Output Format\n\n### JSON Format\n```json\n{\n  \"id\": \"18234567890abcdef\",\n  \"threadId\": \"18234567890abcdef\",\n  \"timestamp\": \"2025-07-01T10:30:00Z\",\n  \"subject\": \"GitHub notification\",\n  \"from\": {\n    \"name\": \"GitHub\",\n    \"email\": \"noreply@github.com\"\n  },\n  \"to\": [\n    {\n      \"name\": \"John Doe\",\n      \"email\": \"john@example.com\"\n    }\n  ],\n  \"labels\": [\"INBOX\", \"UNREAD\"],\n  \"snippet\": \"You have a new pull request...\",\n  \"body\": \"Full email body here...\",\n  \"attachments\": [\n    {\n      \"filename\": \"report.pdf\",\n      \"mimeType\": \"application/pdf\",\n      \"size\": 1024\n    }\n  ]\n}\n```\n\n## Use Cases\n\n- **Monitoring systems** - Alert on specific email patterns\n- **Automation workflows** - Trigger actions based on email content\n- **Data analysis** - Collect email metrics and statistics\n- **Integration** - Feed email data into other tools and systems\n- **Backup** - Archive important emails in structured format\n- **CI/CD** - Monitor build notifications and alerts\n- **Interactive exploration** - Use REPL mode for ad-hoc email searches and account exploration\n- **Filter debugging** - Test and refine Gmail search queries interactively\n\n## Configuration File\n\nCreate a `gmailtail.yaml` file for complex configurations:\n\n```yaml\n# Authentication settings\nauth:\n  credentials_file: ~/.config/gmailtail/credentials.json\n  # auth_token: ~/.config/gmailtail/service-account.json\n  cached_auth_token: ~/.config/gmailtail/tokens\n\n# Email filtering settings\nfilters:\n  query: \"label:important\"\n  # from: \"noreply@github.com\"\n  # to: \"me@example.com\"\n  # subject: \"alert|error|warning\"\n  # labels: [\"important\", \"inbox\"]\n  # has_attachment: true\n  unread_only: true\n  # since: \"2025-01-01T00:00:00Z\"\n\n# Output formatting\noutput:\n  format: json-lines\n  include_body: true\n  include_attachments: true\n  max_body_length: 500\n  pretty: false\n  # fields: [\"id\", \"subject\", \"from\", \"timestamp\", \"labels\"]\n\n# Monitoring behavior\nmonitoring:\n  poll_interval: 60\n  batch_size: 20\n  tail: true\n  # max_messages: 1000\n\n# Checkpoint settings\ncheckpoint:\n  checkpoint_file: ~/.config/gmailtail/checkpoint\n  checkpoint_interval: 120\n  resume: true\n\n# Logging\nverbose: false\nquiet: false\n# log_file: ~/.config/gmailtail/gmailtail.log\n```\n\n## Authentication Setup\n\n### OAuth2 (Recommended for personal use)\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create or select a project\n3. Enable Gmail API\n4. Go to \"Credentials\" → \"Create Credentials\" → \"OAuth 2.0 Client ID\"\n5. Choose \"Desktop application\"\n6. Download the JSON file\n7. Use with `--credentials path/to/credentials.json`\n\n### Service Account (For server/automated environments)\n\n1. In Google Cloud Console, go to \"Credentials\"\n2. Create \"Service Account\"\n3. Download the JSON key file\n4. Use with `--service-account path/to/service-account.json`\n\nNote: Service accounts need domain-wide delegation for Gmail access.\n\n## Development\n\n### Setup development environment\n```bash\n# Clone the repository\ngit clone https://github.com/c4pt0r/gmailtail.git\ncd gmailtail\n\n# Install with development dependencies\nuv sync --extra dev\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n### Running tests\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=gmailtail\n\n# Run specific test file\nuv run pytest tests/test_config.py\n```\n\n### Code formatting and linting\n```bash\n# Format code with black\nuv run black .\n\n# Sort imports with isort\nuv run isort .\n\n# Run flake8 linting\nuv run flake8 gmailtail/\n\n# Run mypy type checking\nuv run mypy gmailtail/\n```\n\n\n\n## License\n\nMIT License - see LICENSE file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc4pt0r%2Fgmailtail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fc4pt0r%2Fgmailtail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fc4pt0r%2Fgmailtail/lists"}