Back to the talks Previous by track: Emacs as a fully-fledged reference manager Next by track: Reading and writing emails in GNU Emacs with Gnus Track: General

org-gmail: A Deep Integration of Gmail into Your Org Mode

Bala Ramadurai (he/him) - https://balaramadurai.net, bala@balaramadurai.net

Format: 24-min talk ; Q&A: BigBlueButton conference room Etherpad: https://pad.emacsconf.org/2025-gmail
Etherpad: https://pad.emacsconf.org/2025-gmail
Status: TO_REVIEW_QA

Talk

00:00.000 Before we begin 00:19.840 The 4-year overnight success 01:02.800 The real title 01:15.600 Why not gnus/mu4e/notmuch? 01:34.280 The honest answer 02:17.920 The org-gmail philosophy 02:49.440 Architecture (the boring but important slide) 03:21.200 Demo 1: From gmail to org 04:37.480 Settings 05:43.040 Downloading 07:56.880 Replying 09:33.680 Label management 10:57.160 Refiling 12:04.120 Archiving 13:37.140 Action commands 15:53.680 Org Agenda 16:28.280 Trash 17:07.440 Real workflow: GTD 17:40.560 Real Workflow: P.A.R.A. 18:35.960 What this is NOT 20:07.680 Technical decisions 20:54.760 Roadmap 21:41.440 Contributing 22:32.940 The big picture 22:41.120 Let's connect

Duration: 23:04 minutes

Q&A

Listen to just the audio:

Duration: 24:55 minutes

Description

For many, email is the starting point for tasks, projects, and reference material. While Emacs has powerful, full-featured mail clients like Gnus and mu4e, they are designed to manage the entire email workflow.

org-gmail offers a different approach: it is not a replacement for a full mail client, but a tool for deeply integrating your most important emails into your Org Mode knowledge base.

This talk will introduce org-gmail, a package that allows users to fetch entire Gmail threads or individual messages and save them as entries in Org mode files. The core idea is to triage emails in the Gmail interface and pull relevant threads into Org Mode, where they can be linked to tasks, notes, and projects.

We will explore the key features of the package, including:

Fetching emails by label and syncing new messages for previously downloaded labels.
Managing labels directly from Emacs, including creating, deleting, editing, and bulk-moving threads between labels, which updates both Gmail and the corresponding :LABEL: properties in your Org files.
Performing common email actions from within Org Mode, such as replying, forwarding (delegating), snoozing (deferring), and moving messages to the trash.
Integrating emails into a task management workflow by creating actionable sub-tasks that appear in the agenda.

The session will demonstrate practical use cases for both Getting Things Done (GTD) and the P.A.R.A. method (Tiago Forte). For GTD, we'll show how to process a Gmail inbox, download actionable emails into an Org file, and then defer, delegate, or create TODO items. For P.A.R.A., we'll demonstrate how to label emails according to projects and areas, and how to archive them systematically using the bulk-move feature.

By the end of the talk, attendees will understand the unique workflow org-gmail enables and how it can help them turn their email into a structured, actionable part of their Org Mode system.

About the speaker:

Bala Ramadurai is an entrepreneur, professor, author, coach, consultant, and podcaster. He is the CEO of Spirelia, a company that helps innovate. He has authored a book called Karmic Design Thinking and holds 3 patents.

In this talk, Bala will introduce org-gmail, a package he developed to seamlessly integrate Gmail with Org Mode. You will learn how to transform your important emails into actionable tasks and reference material, leveraging the power of Org Mode for a more organized and productive workflow that supports methodologies like GTD and P.A.R.A.

Transcript

[00:00:00.000] Before we begin

Hello everyone. My name is Bala Ramadurai. Today I'm going to be talking about org-gmail. That's something that I put together. This is what I call gmail meets org mode. And they get along too. Let's talk about email and how to manage email via org mode.

[00:00:19.840] The 4-year overnight success

This project is a four year overnight success. It was in 2021. I said, Hey, wait a second. It'll be so cool if we can integrate Gmail with org. So I started trying out new things. And immediately I realized this is a much larger project than I thought. So it lived in someday maybe.org for about three years. Enter 2024 AI arrives and in 2025 I had a working prototype in 24 hours flat. So three years and 364 days, nothing much happened and one day it actually got it working. Sometimes procrastination is just waiting for the right tools.

[00:01:02.800] The real title

The real title should have been org mail for people who like org mode more than email. The Gmail monster that has always been attacking us. Okay, but we still have to deal with email.

[00:01:15.600] Why not gnus/mu4e/notmuch?

One of the most common questions that I've got so far. Why not gnus or mu4e or notmuch, or other tools. They are amazing. Use them if it works for you, absolutely. Just go right ahead. If it works for you, don't change anything because this looks cool.

[00:01:34.280] The honest answer

Well, the honest answer for me is that they want to be your email client. That's not what I am after. I don't want an email client. I have enough email clients already. I don't want one more. And they require 500 lines of config. I've tried it. It's a lot of maintenance for myself, I still have those somewhere. The mu4e config or the gnus config. They struggle with Gmail's labels, threading, messages and deletion. I find it tough, and it's either all in emacs or nothing. It cannot be a combinatorial approach, is what I realized. So I said, why can't we have both? I want the org mode's focus and Gmail's flexibility.

[00:02:17.920] The org-gmail philosophy

Org-gmail philosophy is very simple. You triage in Gmail. Use the fast web UI for the easy stuff and process in org mode. Pull important threads where you do real work. And of course, a two way sync is possible. Changes flow both directions. Big inspiration has been org-gcal. I named it org-gmail because I saw org-gcal. It was so cool. I really wanted it. Think of it like an org capture for email, but just bidirectional.

[00:02:49.440] Architecture (the boring but important slide)

Alright, the architecture (boring, but important slide) is that Gmail interacts with Python via an API and interacts with Emacs Lisp. User commands, org formatting, all that magic is done on the Emacs side with Lisp. Python side handles the Gmail API, OAuth, json wrangling and Gmail API handles the actual email data. You can do pip install, add to the load path, and 10 minute OAuth setup, you are all set.

[00:03:21.200] Demo 1: From gmail to org

We'll switch over to demo from gmail to org. How do you go about doing that? I will start off with a demo folder that I have. It has this tree structure. Ignore the tilde files. So this is what it contains. An org folder with all the working directory, the actual where the life of org mode is. And I have a credentials.json, this is for logging into Gmail. This is a file that you can download. The instructions are in my README in the repository. You can find out how to get yourself a credentials.json. It's not very difficult. Once you have these, you're all set. All you need to do is if you have straight or any of the other VC packages ready, that you can take a Git repository and have that in your folder, you can do that, or you can do it like this. Have a Git clone. Like I'm doing it right now. Just clone it, keep it in. And now you'll see that the Gmail is already there. There are two files that are really ultra important, which is, gmail_label_manager.py and org-gmail.el. These are the two files that do the email processing. I have a plain vanilla Emacs that I'm going to use for the demo.

[00:04:37.480] Settings

These are a few settings that you will need in order to get going. So one is the Gmail itself, the elisp, and the Python script. You'll need to require the package. The org agenda files need to be set. If they're already there, then yes, it needs to include the org files. Main settings are, you need an org file in order to download all the emails from Gmail. You need the credentials path. You need the Python script, wherever it is pointed to that. The date drawer, you can customize it to whatever you want. I call it org-gmail. You can set it to ignore certain labels, not to download it. You're not interested in certain labels being downloaded. You can set that and process time out of 300 seconds. These are some things to keep life sane in this plain vanilla emacs. So I have this refile targets and stuff. That's the main org-gmail settings are all here. I'm going to eval this buffer so that we have all of it and we are all set. So we have org-gmail ready to work right now.

[00:05:43.040] Downloading

The first thing I'm going to show you is org-gmail-download-by-label. This is the demo Gmail that I have. They all have some kind of test emails and I'm going to label them. I've created this hierarchy of labels here based on Tiago Forte's PARA - Project, Area, Resources, Archives structure. 1Projects, DemoProject1, 2Areas, DemoArea, 4Archives, 2025, OldProject. I've labeled them inside my Gmail. Okay, now let's go to Emacs and we will now download these things, but before downloading them, you will need to authenticate. So for that, you can start with any org-gmail command. So I'm going to take org-gmail-download-by-label. When I press that, it immediately opens a session in my browser. Okay? What you can't see is a list of my Gmail accounts that I'm going to select. I'm going to select my one Gmail account, and I'm going to show you the next screen. So in this screen, you'll have to continue and select, and the authentication is completed. So once it's, this is done, you can close this. Come back to Emacs and you will have Select Gmail. So it has tab support. If you click tab, it will tell you what all labels are available. I can pick anyone. 1Projects/DemoProject1, and let's see what happens. It starts downloading and it downloads. And all three messages, four messages, five messages. Six, seven. There are 11 messages in total, and it's downloading all of them. ~/demo/org/0Inbox. That's where I have it. And here are the emails. They're all in org mode, format. All the emails are in here. Since it's org mode, it can fold them all and you will see those emails. So these are five emails that are present for the DemoProject1.

[00:07:56.880] Replying

The next one I wanted to show you was reply without leaving emacs. Let's go back to emacs. How am I going to reply? org-gmail-reply-at-point. That's how I'm going to reply. Reply all or reply. Okay. Let's first find out what is the email all about. Okay. There's just one sender with just one recipient. So the reply all or reply doesn't make a difference. Okay? So we will reply at point and if it's Reply All, it includes my own email as well. In this, my email is .mx. Okay. Cc, I can cc anybody I want and I won't do that. I have a Gmail reply window. Split window here. C-c C-c is what will send the reply. C-c C-k is what will cancel the reply. I want to reply. So let's say test reply from within emacs and bala@balaramadurai.net should receive this email. Okay. Initial successfully reply sent for this email id. Okay. A feature request I can already imagine is the reply also appearing at the bottom of this. It's not yet there. In the next version I will have that. Let's check if I've have sent that email. Let's check in the sent box. I just checked in the sent and yes, a test reply from within emacs, does show up. Okay, great. That works.

[00:09:33.680] Label management

The third demo is going to be on label management. How do I manage labels? Let's see. Let's go back to emacs. Suppose, I am not keen on this DemoProject1 for this. It should belong to DemoArea, okay? For this thread itself doesn't belong to this. Let's do org-gmail-edit-label-at-point. Well, I don't want one project at all. It should be under 2Areas/DemoArea. I don't think it, it's not tab supported. You should know this. I will. That's another feature request. 2Areas/DemoArea. And when I say this, it should update it. Yes, it has updated it. So you can see that it has updated the label here as well. We can go check if it has indeed changed it in our... what is the name of the email? It's a test mail for one project demo and the date is at 3 12. Let's check if DemoArea has it. It's not refreshed, but there are two, two emails now under DemoArea. It's obviously done the job well. It's happening as expected. I just turned this back from DemoArea to DemoProject1. If you decide that I want to move all of DemoProject1 to archive, I'm done with the project.

[00:10:57.160] Refiling

Oh, by the way, you could... that's the whole point of this is to have all of this refiled into your project, you can do that. I don't know if I have that. Yes, I have demo project one and I could have emails and I created a node and I moved everything there to that folder so that when I want to look at the demo project. Let me look at this. In that context, in the project context and email, I have notes, let's say, and one of the emails is a note. And I want to be able to keep it that way. I could refile it and put it under notes as well, saying that this has some password, it has some reference that I need to have it there. I can have it under notes as well. So that's the advantage. Once it's inside the org mode system, you can do many things that are usually org-modesy. So you can do all of that within your org mode with emails, manipulate them, see it under a context, reply to that. All of that can happen right within your project context.

[00:12:04.120] Archiving

You're done with this project. You want to move to archive. So what you need to do is you don't have to be here, you can do it this from anywhere. Bulk movement of labels, you can do it. If you had consult, embark, ivy, or helm, this will show up as a dropdown and it looks neater. This, I'm using a vanilla emacs, so this is what you would see, but it has tab support. You can use that. So I want to transfer 1Projects/DemoArea1, I want to move it to archive. So let's say 4Archives is the folder. So 4Archives/2025 already set this up. I have not created this label in Gmail. So do I need to go back to Gmail and create that? No, not at all. You can do this from the comfort of your org mode. Go in here and enter this. Let's see what happens. So it found that it is not there. So it created a new label and it's now moving all of the emails, all of those threads into archives without deleting 1Projects/DemoProject1. So it still has 1Projects/DemoProject1 and it also updated the labels here. So the project has been moved. If you want to move it to archive this entire... You can do that too. Let's see if it has archives. Yes, it has archives and I have it... have a heading called 2025. My demo project can be moved there and I'm done here. My project was done. All the emails are moved to archive. So is this project from my project folder. You can integrate it into your workflow, your org mode workflow.

[00:13:37.140] Action commands

Next, we have action commands. What all can you do with singular emails? You can do four things with single emails. Delegate, defer, act on it or trash at point. Defer. Doesn't seem to work yet. That is a snooze part. Doesn't seem to work yet. That's another bug. That's the second bug I have in my package. But the rest of them work. Delegate is to move it to somebody so they can do the job. Act is you will do it with a context with a to-do which will show up in your agenda. Trash the email from your Gmail, and you are done. Okay, let's do that. Let's go back to emacs. I just moved everything back to DemoProject1. I moved everything back so that I can demonstrate the four actions that I'm showing. At least three actions. One of them doesn't work yet. So if I want to delegate it to somebody in this case myself, but I can delegate it to anybody I want. So how do I do that so I can delegate this, or delegate is org-gmail-delegate-at-point. Move the cursor to the email, delegate it to this guy balaramadurai.net. You can add a note saying, Hey, act on task quickly. Boss is watching. Okay? So you can say yes, and this thread gets forwarded to your colleague and so that they can take this up. It has indeed arrived here. You can see. Boss is watching. The test reply was also arrived here. You can also see that email. So that was delegate. So how do we set up actions? So let's not mess this email. This is the second email. How do you act on it? That's an action you set for yourself is add action at point, and you do that. What action can you set for yourself? Write a long report using an LLM. Okay, so it's changed the status to a to-do task. And the to-do is right here. Now, here you can schedule it to say tomorrow 9:00 AM. So there you go. At 9:00 AM I'll be looking at this.

[00:15:53.680] Org Agenda

Now here's the cool part. You can actually find the whole thing in org agenda. So my entire email threads are all in the org agenda. They're all present here and my task associated is also here in the agenda. This is marked TODO, means I haven't acted on that email. It's still pending. And what do I have to do is right here within here, which is the action that I have to carry on in the DemoProject1. You can see that demo project one is showing up in the bottom. Okay. It's cool way you can also see it in the agenda.

[00:16:28.280] Trash

I am not interested in this email at all. Let's say I, I want to delete it. Let's see. Yes, I finished the task. Now the task is finished. I really don't want to see this email, this message alone. Alright. Easy peasy. Let's do Gmail Trash at point. And you say, message, I don't want to delete the entire thread. Yes. Delete it. Delete the message alone. And it's gone. But it's not gone. It's gone to the trash. The entire subtree was deleted and we have a clean flow here. I have archived, it is still in the archive, but it's still active according to my Gmail folder.

[00:17:07.440] Real workflow: GTD

Next I'm going to show you is real workflow capture. You can use label in email with ToProcess downloaded to the inbox.org, and do one of these you've already seen. Later still doesn't work. I will get it to work, but hopefully by the time the conference is up, you will have the feature up and ready. Rest of the stuff works, delegate works, trash works, and add action works. We are in weekly review can have an email context, not just links to an external URL.

[00:17:40.560] Real Workflow: P.A.R.A.

In the P.A.R.A Our Project, Areas, Resources and Archives structure, you can have Gmail labels mirror your PARA structure. You can have that within your org mode structure, and you can mimic that very well. All the emails embedded in your own structure and you can download it by label in the place you want. I'm still working on that feature where you can have it inside the project structure itself rather than an index.org. It'll take some time, but I will do it. But right now you can refile it once it's in the index.org or any other file you choose, and then you can bulk move labels to archive and move that entire project repository to your archive also. That works very well. And your org files and Gmail stay in sync effortlessly, and the whole email part of it becomes part of your knowledge management system. Okay.

[00:18:35.960] What this is NOT

We have reached the end of the demo. Hopefully you understood what org-gmail was all about. If you have any questions, let me know, but some bits of warning, I wanted to give you what this package is not, it's not a full fledged email client. It's meant for label management and importing some emails that you wanted or you're interested in to the context of your projects or areas or your GTD context. It is not a replacement for gnus, mu4e or notmuch. It is not a way to read all your emails in emacs. It cannot handle a large server load for sure. It is not offline capable. It needs API access. So bear that in mind. What it is, is a bridge between gmail and org mode. It's a way to manage important email threads. So you can keep updating threads. Whenever there's a reply, you keep downloading it to that thread. If you want to keep track of what's going on, what is the logical way you can all see it. You can even use ellama or one of those to make sense of the conversation. If it's a long longish thread, it's a power tool for the getting things done or Tiago Forte's PARA method. I've used PARA for a long time now. I'm a power user of PARA, so to speak, so I find this extremely useful myself. It's about 800 lines of Python and about 300 to 500 lines of elisp. It's usable in 10 minutes, but can remain powerful for years.

[00:20:07.680] Technical decisions

So some technical decisions that I took. Why Python plus Gmail, API. Gmail API is better at handling than an imap with all the other metadata. I found it easier. Python has excellent Google API libraries. Email calls Python via the call-process. json is the interchange format. Why not pure elisp? For one, OAuth 2.0 flow is a bit complex. I found it a bit complex to meander on. That's probably why it took me three years, 364 days to get over it. Gmail API Client libraries are mature, easier to test/debug separately and lets emacs do what it does best, which is text editing. Pragmatism over purity, the emacs way since 1976.

[00:20:54.760] Roadmap

Okay, some roadmap here. But near term I want better error messages. It still gives me python error messages. There are some asynchronous operations there's no blocking going on. It needs a search integration soon. Attachment I have not yet touched. That's a big big if, I don't know how to integrate with org-attach, I'm still wondering how to do that. Perhaps I should be able to interact with Outlook also, fast mail, proton mail. I don't know AI summaries of thread. I'm thinking ellama could do it, but I'm not very sure. Calendar integration is a nice idea, but org-gcal and org gmail... How will they interact? How will that work? I'm still not sure. I use them separately. And any other feature requests that you may have, just let me know.

[00:21:41.440] Contributing

What I may need help with if you have the time and you're interested in this project, is to test it on macOS and Windows. I use Linux. I use it on Debian. It works fine. OAuth edge cases. I'm not sure how it works. It shows me some error or the other here and there. Definitely documentation needs improvements. Other email provider expertise will be welcome. What's ready is, GitHub repo with issues. You can start with that could be great if you can tell me some issues with that. Some kind of development guide. I am not a programmer. I vibe-coded most of it. So a development guide, a true blood developer, if they can come and tell me, here is what you should be doing, I'm more than happy to listen to that. And probably a test suite. I do that manually. All of this, some kind of help with that will also work.

[00:22:32.940] The big picture

The big picture is org-mode and Gmail can be friends. They can bond over a cup of coffee.

[00:22:41.120] Let's connect

Let's connect. Here are my details and I am all game to listen to your question and answers. I'm happy to give you any answer or responses that I find. Please do connect with me on LinkedIn. I have my website here, and please do fork or install org-gmail and let me know what you think. Let's talk about taming email. Thank you very much.

Q&A transcript (unedited)

I first of all want to address the feedback. You're absolutely right. I should have stuck to one theme. Unfortunately, I was using vanilla Emacs and not my own config. So to show that it can work, apologies for that. I will keep that in mind the next time I do such a demo. The first question, I mean, the feedback was considered using similar background dark only or light only throughout the help, throughout the help with iStream. The question, the first question is, should I know all my contact email address by heart or is some kind of contact list? Unfortunately, right now, this is just to get started. So it is, you have to know it by heart, but I take this as feedback. I will write this down for myself as a feature request. I will make sure that all contacts or some kind of tab support is present for email addresses. I do not use the org system for replying so much. I use it for knowing the context. So I don't really reply using the org mode itself to reply. So I did not focus on that feature. But this is doable. We can certainly add a tab support for any contacts that you may have, org contacts. Or I don't know if there's any other package that does that. So if it is, let me know. Org contacts is what comes to my mind. The second question is, what would it take to use the org pieces of this with? offline IMAP or other non Gmail mail setups. I use fast mail. Currently, I use only Gmail because that's my workflow and it works with a Gmail API. So which means the Python script that goes along with it only works with Gmail and no other system for now. This is the current package. However, yes, I will note this down. I don't know what it will take to include this offline IMAP setup or any other non-Gmail setup. Let me tinker with it and find out what it will involve. So give me some time, maybe I will get to it. Sorry, sorry. Oops. Okay. Okay. May I continue? Hi, Bella. Yes, please. Sorry for the confusion. Hi, Amin. All right. So the next one is, do you worry about sending some info to a wrong person due to some unseen technical issues, for example, due to memory overflow? Again, I have not been focusing on replying from within Emacs. so much, or using my package, I usually do it through the Gmail interface. I usually use this to get the context within the project, download all the emails, make sure that I have acted on emails which Gmail doesn't do so well. I don't know what the action is. I don't want to use Gmail as a to-do list. Org Mode is great at this. Any work I have to do, any reports I have to compile, all of that Org Mode does. I don't use it for replying or doing its actions around the email, which I focus on. But point taken, let me see if there is a like Gmail offers. you know, for 10 seconds or something you can still undo so that it doesn't go out of your email if you made a mistake or if there's a problem with your, you know, Gmail or email sending should sort of stop. Let me think about that. So, I've not paid attention to that, but I'll take your point. The next one, you should say what org-gmail is and not its goals and non-goals, which in this case is more helpful to help people get their head around this. You had some good ones in your slides, but not your GitHub page. Okay, great. Okay, so I will definitely take the information from the slides and give it to, I mean, put it back into my readme. It's been a while since I updated ReadMe, and you're absolutely right. It probably doesn't say why you need org email. So that would be definitely something that I can do. Wanting to add the goal is an easier way to add one-off email into org mode and org agenda workflows and first. Love seeing a different way of looking at and working with email. Thank you so much for that. Yes, that's the idea here is if we can integrate email and I think there is memacs, you know, that's one package that I love. It can integrate all of the other stuff into your org mode. That worked, but I like email and dealing with email. That is my single source of truth outside of org mode. So that's the only one I need for now. And I like seeing the action and the history on my org agenda. That's one of the reasons why I built this package. And I hope that answers that. There is one more saying, how does it handle attachments? If it doesn't, do you have a plan to add this feature? Attachments is a bit tricky for me right now because I don't understand org-attach so well. I don't use org-attach, but you're absolutely right. It does make sense to have org-attach also. And it's definitely in my plan to include org-attach. I don't think I talked about it in my talk, but I definitely have that idea. First I have to wrap myself, my head around the idea of org-attach and how it, because I don't like, what I don't like about org-attach, I'll tell you, is default is, it opens a new folder called data and there are, it uses a unique code and there are subfolders in it, which I do not appreciate because I want all those files also to be within the same context. of my project or area. And that's one of the reasons I, and I'm sure you can customize that. There are ways to do that, but I have to pay more attention to this. Right now, all of the attachments are dealt with in Gmail, which is not a good system to handle that because it's so out of context. And there are like 25 contexts in the same inbox, which I do not appreciate. So even the attachments are like that. But Org Mode has a much better way of handling it, or Emacs has a much better way of handling it. I will definitely put my attention to this and get this feature out. This is all customer feedback for me, so to speak. So I would definitely request all of you to try it out. And tell me, you know, good or bad things about the package. And you've been very candid so far. Please be so. So, you know, so be it that be candid with your feedback and I will get to know how to go with this. With so much, I mean, I'm not an expert in Elisp, but I have a workaround, which is I have generative AI support, which has done well with me. I test the software better, so I can use the generative AI to help me with the coding, but I can test it so that it works for me. And I would request your help also in testing this software. So for sure. Thank you so much for your question. If there are any more, I can definitely answer them.

Questions or comments? Please e-mail bala@balaramadurai.net

Back to the talks Previous by track: Emacs as a fully-fledged reference manager Next by track: Reading and writing emails in GNU Emacs with Gnus Track: General