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.

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.
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.
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.
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.
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.
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.
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.
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.
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 by 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.

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.
Ctrl-c Ctrl-c is what will send the reply.
Ctrl-c Ctrl-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.

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.
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.
You're done with this project.
You wanna 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 does 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.

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.
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.
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.

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.
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.
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.

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.

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.

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.

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

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.