GmailTail: Transform Your Email into an Automation Hub

Last modification on

I was having my morning coffee last Tuesday when I got hit with the usual email avalanche: three GitHub notifications, two CI/CD failure alerts, a customer complaint, and yet another "urgent" report from our analytics team. Sound familiar?

Here's the thing that bugged me: I found myself doing the same dance every morning. Open email, read GitHub notification, manually check the PR, copy the issue number, paste it into Slack... rinse and repeat for each alert. It felt like I was a human API gateway between my inbox and the rest of my workflow.

Then it hit me – what if I could treat my email like a log file? You know, just tail -f it and pipe the output to whatever tool I needed? What if instead of manually processing each email, I could turn my inbox into a real-time data stream?

That's how GmailTail was born. It's basically tail -f for Gmail, but with superpowers. Real-time monitoring, smart filtering, JSON output, and it plays nice with every tool in your terminal.

Why I Built This Thing

My Email Workflow Was Driving Me Crazy

Let me paint you a picture. Every morning, I'd wake up to:

  • 15+ GitHub notifications (because apparently everyone loves late-night commits)
  • At least 3 "Build Failed" emails from our CI pipeline
  • Customer support tickets that need immediate attention
  • Daily reports from various services that I'd manually copy-paste into spreadsheets

The kicker? Email clients are built for humans, not automation. They're great for reading and replying, but terrible for integrating with scripts and workflows. And Gmail API? Don't get me started – it's like using a sledgehammer to crack a nut for simple tasks.

I wanted something dead simple:

  • Watch my inbox in real-time (like watching logs)
  • Filter emails with Gmail's powerful search
  • Output clean JSON that I can pipe to any tool
  • No complex API setup, just a simple command-line tool

What GmailTail Actually Does

The Basics (It's Pretty Straightforward)

Want to watch your inbox in real-time? Just run:

gmailtail --tail

That's it. New emails pop up as they arrive, formatted as clean JSON.

Getting Fancy with Filters

Here's where it gets interesting. Say you only care about GitHub notifications:

gmailtail --from "noreply@github.com" --tail

Or maybe you want to catch all those pesky error alerts:

gmailtail --query "subject:error" --tail

You can even get creative with complex queries:

gmailtail --query "from:github.com AND label:important" --tail

Different Output Flavors

Need the email body too? No problem:

gmailtail --format json-lines --include-body --max-body-length 500 --tail

Only want unread emails with attachments? Easy:

gmailtail --unread-only --has-attachment --tail

Interactive Mode (For the Explorers)

Sometimes you just want to poke around:

gmailtail --repl

Then you can play around:

gmailtail> unread important 5
gmailtail> query from:github.com
gmailtail> labels

How I Actually Use This Thing

Auto-handling GitHub PR Notifications

This one's my favorite. I used to manually check every GitHub notification. Now? I just pipe them to a script:

gmailtail --from "notifications@github.com" --tail | \
  jq -r 'select(.subject | test("Pull Request")) | 
         .subject | capture(".*#(?<number>[0-9]+).*") | .number'

Boom. PR numbers extracted automatically. I can feed these into Slack bots, update project boards, whatever.

Never Miss a Build Failure Again

Our CI used to fail silently (well, not silently, but I'd miss the emails). Now I get desktop notifications:

gmailtail --query "subject:build AND subject:failed" --tail | \
  jq -r '.subject' | \
  while read subject; do
    osascript -e "display notification \"$subject\" with title \"Build Failed\""
  done

My Mac literally yells at me when builds break. It's beautiful.

Production Alerts Go Straight to Our Dashboard

We have a monitoring dashboard, but it was annoying to manually add email alerts. Now they flow in automatically:

gmailtail --query "subject:alert OR subject:error" --tail | \
  jq '{time: .timestamp, from: .from.email, subject: .subject}' | \
  curl -X POST -H "Content-Type: application/json" \
       -d @- http://localhost:3000/api/alerts

AI-Powered Email Summaries (Because Why Not?)

Got important emails but no time to read them all? Let AI do the heavy lifting:

gmailtail --label important --include-body --tail | \
  jq -r '.body' | \
  while read body; do
    echo "$body" | curl -X POST \
      -H "Content-Type: application/json" \
      -d '{"text": "'"$body"'"}' \
      https://api.openai.com/v1/chat/completions
  done

I get AI summaries of important emails in real-time. It's like having a personal assistant who never sleeps.

Configuration Made Easy

I got tired of typing the same command-line flags every time, so I added YAML support. Just create a gmailtail.yaml file:

auth:
  credentials_file: ~/.config/gmailtail/credentials.json

filters:
  query: "label:important OR subject:urgent"
  unread_only: true

output:
  format: json-lines
  include_body: true

monitoring:
  poll_interval: 30
  tail: true

Then just run:

gmailtail --config gmailtail.yaml

Much cleaner, right?

Getting Started (The Easy Part)

What's Under the Hood

Nothing fancy – just solid Python with some good libraries:

  • Python 3.8+ (you probably have this already)
  • Gmail API (Google's official stuff)
  • Click for the command-line interface
  • OAuth2 for secure authentication
  • YAML support because JSON config files are painful

Installation

Clone it and install:

git clone https://github.com/c4pt0r/gmailtail.git
cd gmailtail
uv sync

The OAuth Dance

Yeah, you need to do the Google OAuth thing. It's annoying but necessary:

  1. Go to Google Cloud Console
  2. Enable Gmail API
  3. Create OAuth2 credentials
  4. Download the credentials.json file
  5. Run: uv run gmailtail --credentials credentials.json --tail

First time you run it, it'll open a browser window for authentication. After that, it just works.

What's Next

I've got some ideas brewing:

Plugin System: Imagine custom processors like a "morning report generator" that summarizes overnight activity.

More Output Formats: CSV, HTML, maybe even a simple web interface for teammates who live in browsers.

Built-in AI: Instead of piping to external APIs, why not have summarization and analysis built right in?

Multi-account Support: Because some of us have way too many email accounts.

Web UI: A simple dashboard for people who prefer clicking over typing commands.

Why This Matters

Here's the thing – GmailTail isn't just another email tool. It's about turning your inbox from a passive information dump into an active part of your workflow.

Think about it: your email is already a central hub for notifications, alerts, and updates. Instead of manually processing each one, you can now:

  • Automate responses: Connect to databases, notification systems, whatever you need
  • Integrate with existing tools: jq, curl, AI models, Slack webhooks – they all play nice
  • Build custom workflows: Create your own email-driven automation without complex programming

It's like having a personal assistant who never sleeps, never gets tired, and processes your emails faster than you can blink.

The best part? It follows the Unix philosophy – do one thing well and play nicely with others. You're not locked into some complex platform; you're just adding a simple tool to your existing toolkit.

Want to Try It?

If you're tired of manually processing emails and want to automate your inbox workflow, give GmailTail a shot. It's saved me hours of manual work every week, and I think you'll find it useful too.

Repository: https://github.com/c4pt0r/gmailtail
License: MIT
Contributions Welcome: PRs and stars appreciated!

Stop being a human email processor. Let GmailTail turn your inbox into an automation engine.