org-gmail: When Gmail Finally Met Org Mode (and They Actually Got Along)

Email and I have always had a complicated relationship. I love Gmail’s web interface for quick triage, but my real work happens in Org Mode. For years, I tried the “all-in-Emacs” approach with mu4e and notmuch, but 500+ lines of config later, I realized I was fighting Gmail rather than working with it. That’s when I decided to build a bridge instead of a replacement.

The 4-Year Overnight Success

Here’s a confession: I first had the idea to integrate Gmail with Org Mode back in 2021. “I should build this!” I thought. And then… crickets. The idea lived peacefully in my somedaymaybe.org file for three whole years.

Then AI arrived.

In 2025, with the help of Gemini and Grok, I had a working prototype in 24 hours.

Lesson: Sometimes procrastination is just waiting for the right tools.

The Frustration That Started It All

Picture this: It’s a typical Monday morning. I’m doing my weekly review in Org Mode, going through my projects and next actions. Then I remember there’s an important email thread about a client project. I switch to Gmail, find the thread, copy-paste the relevant bits into my Org file, manually add properties, link back to Gmail… and by the time I’m done, I’ve lost my flow completely.

Sound familiar?

I’ve been an Emacs user since my undergrad days (yes, the same Emacs that helped me write my book). I know there are powerful email clients inside Emacs - Gnus, mu4e, notmuch. They’re amazing pieces of software. But they all want to be my email client. They want me to go all-in. And frankly, Gmail’s web UI is fast, and I’ve got decades of muscle memory with it.

What I wanted was simpler: a way to pull important email threads into my Org files when I need them, and have changes flow both directions.

Why Not Gnus/mu4e/notmuch?

Short answer: They’re amazing. Use them if they work for you.

The honest answer:

• They want to BE your email client
• They require ~500 lines of config (minimum)
• They struggle with Gmail’s labels and threading
• They make you choose: “All in Emacs” or nothing

org-gmail says: “Why not both?”

The org-gmail Philosophy

1. Triage in Gmail - Use the fast web UI for the easy stuff
2. Process in Org Mode - Pull important threads where you do real work
3. Two-way sync - Changes flow both directions

Think of it as org-capture for email, but bidirectional.

Architecture (The Boring But Important Part)

┌──────────┐    ┌──────────────┐    ┌────────────┐
│          │◄───┤              │◄───┤            │
│  Gmail   │    │ Python + API │    │ Emacs Lisp │
│          │───►│              │───►│            │
└──────────┘    └──────────────┘    └────────────┘

• Emacs Lisp: User commands, Org formatting
• Python: Gmail API, OAuth, JSON wrangling
• Gmail API: The actual email data

Installation: pip install + add to load-path + 10 min OAuth setup

The setup is intentionally minimal - about 20 lines of config versus the 500+ you’d need for a full mail client:

(use-package org-gmail
  :straight (org-gmail :type git :host github :repo "balaramadurai/org-gmail")
  :config
  (setq org-gmail-org-file "~/Documents/0Inbox/index.org")
  (setq org-gmail-credentials-file "~/path/to/credentials.json")
  (setq org-gmail-python-script "gmail_label_manager.py"))

That’s it. You’re ready to go.

Real Workflow: GTD Meets Gmail

I’ve been using this with my GTD workflow, and it’s transformed how I process email:

1. Capture: Label in Gmail (ToProcess)
2. Clarify: Download to inbox.org with M-x org-gmail-download-by-label
3. Organize: At point, decide:
   • Quick reply? org-gmail-reply-at-point
   • Later? org-gmail-defer-at-point "tomorrow"
   • Task? org-gmail-add-action-at-point
   • Delegate? org-gmail-delegate-at-point
   • Trash? org-gmail-trash-at-point

Your weekly review now includes email context, not just links.

Here’s what a downloaded email looks like in Org:

** [[https://mail.google.com/mail/u/0/#inbox/thread-id][Client Website Feedback]]
:PROPERTIES:
:EMAIL_ID: abc123
:THREAD_ID: xyz789
:LABEL: 1Projects/ClientWebsite
:FROM: client@example.com
:TO: bala@balaramadurai.net
:SUBJECT: Client Website Feedback
:END:
:org-gmail:
<2025-06-14 Sat 14:30>
:END:

The email content appears here, converted to Org format...

Org properties = Gmail metadata. It’s all connected.

Real Workflow: P.A.R.A.

If you use Tiago Forte’s P.A.R.A. method (which I discussed in my 2024 EmacsConf talk), org-gmail supports your label structure naturally:

1. Gmail labels mirror P.A.R.A. structure:

   • 1Projects/ClientWebsite
   • 2Areas/Finance
   • 3Resources/Emacs
   • 4Archives/2024/ClientWebsite

2. Download by project: org-gmail-download-by-label "1Projects/ClientWebsite"

3. Project done? org-gmail-bulk-move-labels to archive

4. Your Org files and Gmail stay in sync

Email becomes part of your knowledge management system.

The bulk move is the killer feature for P.A.R.A. users - move entire label trees like 1Projects/OldProject to 4Archives/2024/OldProject. All Gmail emails move. All Org files update.

The Comparison Nobody Asked For

What org-gmail Is NOT

• A full email client
• A replacement for Gnus/mu4e/notmuch
• A way to read ALL your email in Emacs
• Offline-capable (needs API access)

What org-gmail IS

• A bridge between Gmail and Org Mode
• A way to manage important email threads in Org
• A GTD/P.A.R.A. power tool
• ~800 lines of Python + ~600 lines of Elisp
• Usable in 10 minutes, powerful for years

We don’t need to live entirely in Emacs. We can use modern tools AND Org Mode. The power is in the connections.

org-gmail is one bridge. What bridges will you build?

My EmacsConf 2025 Talk

I was fortunate to present this package at EmacsConf 2025. The community feedback was invaluable - questions about attachment handling, non-Gmail providers, and reply headers all came from that discussion. (Attachments are now downloaded with Org links, by the way!)

Here’s the talk:

Getting Started

# 1. Install Python dependencies
pip install google-auth-oauthlib google-api-python-client html2text pytz

# 2. Clone repo
git clone https://github.com/balaramadurai/org-gmail

# 3. Add to Emacs config
(add-to-list 'load-path "/path/to/org-gmail")
(require 'org-gmail)

# 4. Setup OAuth (interactive)
M-x org-gmail-download-by-label

The first run will open a browser for OAuth authentication. After that, it’s seamless.

Common Gotchas:

• OAuth consent screen: Use test mode initially
• Token expiry: Re-auth after 7 days (test mode)
• Rate limits: Don’t download 10k emails at once
• Label names: Gmail sanitizes them (spaces become underscores)

The Road Ahead

Current: v1.3 - It works! (on my machine)

Near term:

• Better error messages
• Async operations (no blocking)
• Search integration

Future maybe:

• Other providers (Outlook, FastMail?)
• AI summaries of threads
• Calendar integration
• Your feature request here

Standing on the Shoulders of Giants

This package wouldn’t exist without inspiration from:

• org-protocol - URL handling inspiration
• org-capture - Template system model
• mu4e - Action command patterns
• org-web-tools - HTML parsing ideas

Good artists copy, great artists steal, Emacs users fork.

References

• org-gmail on GitHub
• EmacsConf 2025 Talk
• Getting Things Done by David Allen
• The PARA Method by Tiago Forte

AI Credits

This project is a testament to how AI can accelerate development when you have a clear vision but need help with implementation. Here’s who helped:

• Google Gemini 2.5 and xAI Grok 4 - Assisted with developing the org-gmail package itself, particularly the Python backend (gmail_label_manager.py) and the Emacs Lisp frontend (org-gmail.el). The code comment in the package says it best: “This code was developed with the assistance of Google’s Gemini 2.5 and xAI’s Grok 4.”

• Anthropic Claude (via OpenCode) - Helped write this blog post, weaving together the narrative from the README, the EmacsConf slides, and my own experiences into something (hopefully) coherent.

• DALL-E - Generated some of the slide images used in the EmacsConf 2025 presentation.

The idea sat in my somedaymaybe.org for four years. AI didn’t replace the vision or the domain expertise - it just made the “doing” part dramatically faster. The 4-year overnight success story is real: what would have taken me months of wrestling with OAuth flows and API documentation became a 24-hour prototype session.

The future of coding isn’t AI replacing developers. It’s developers with AI assistance building things they never had time for before.

Now it’s your turn! Are you struggling with email in your Org workflow? Give org-gmail a try and let me know what you think. Drop me a line at bala@balaramadurai.net or open an issue on GitHub!