Townes Mail CLI
Townes Mail CLI lets your AI assistant or agent work with your own Gmail and Google Calendar. It is a command-line tool that runs on your own computer.
WHAT IT DOES
Townes Mail CLI is a command-line tool. You install it on your Mac or Linux computer and sign in to each of your Google accounts once, in your browser, on Google's own consent screen. After that, your AI assistant (for example Claude Code) runs it for you when you ask it to handle your mail or your calendar.
- Search and read your messages and conversations.
- Save the attachments you ask for.
- Write and delete drafts, and send, reply to, and forward mail.
- Archive, trash, restore, label, and star messages, and mark them read or unread.
- List your calendars and your events.
- Find free time.
- Create, change, and delete events.
- Accept, decline, or tentatively accept invitations.
It never permanently deletes messages or conversations: trash keeps them recoverable for 30 days. The only mail it deletes permanently is drafts: the ones you ask it to delete, and a draft it made itself for a send that then failed. It does not change Gmail settings such as filters, forwarding, or vacation replies. Whether guests are emailed about a calendar change is an explicit choice on every command that affects them.
WHO IT IS FOR
Townes Mail CLI is for anyone who wants an AI assistant or agent to work with their own Gmail and Google Calendar. It is in use at Townes & Co today and is opening up to more people. Each person installs it on their own computer and signs in with their own Google accounts, and it works only with the accounts that person signs in.
THE GOOGLE PERMISSIONS IT ASKS FOR
When you sign in, Google asks you to approve three permissions. Each one is needed for part of what the tool does, and it asks for nothing else.
Read, compose, send, and organize your mail
https://www.googleapis.com/auth/gmail.modify So your assistant can search and read your mail, write drafts, send, reply to, and forward messages, and archive, label, trash, or restore them. This permission cannot permanently delete messages; they can only be moved to Trash. It can delete drafts.
View and edit events on your calendars
https://www.googleapis.com/auth/calendar.events So your assistant can list your events, find free time, create, change, and delete events, and answer invitations.
See the list of calendars you have
https://www.googleapis.com/auth/calendar.calendarlist.readonly So the tool can find your calendars by name, use each calendar's time zone, and check whether a calendar allows Google Meet links. It cannot change your calendar list.
HOW YOUR DATA IS HANDLED
Townes Mail CLI talks directly to Google from your computer. Your mail and calendar data never pass through Townes, and Townes never receives them.
The Townes Mail CLI privacy policy, at https://www.townes.ai/mail-cli/privacy, sets out exactly what the tool accesses, what it keeps on your computer and for how long, and how to remove it.
- Your assistant gets the results Each command prints its result only to the program that ran it, usually your AI assistant, to carry out the request you made. The assistant may send it to its AI model provider to produce its response.
- Your sign-in stays in your keychain Your Google sign-in token is stored in your operating system's keychain: Secret Service on Linux, Keychain on macOS (or, if you opt in, in a file only your user account can read).
- Logs without content Local troubleshooting logs are deleted automatically once they are more than 30 days old, the next time the tool runs. They record the commands run, message and event ids, search queries as written, and the addresses of the people you email or invite. Apart from any words that appear in a search query, they never record message bodies or subjects, or event titles, descriptions, or locations, and they never record sign-in tokens.
- No copy of your mailbox
It keeps no copy of your mail or calendar. Attachments are saved only when you ask for
them. A small record of hashes and ids stops a retried command from sending the same
email twice, unless it was run with
--allow-duplicate. - No ads, no selling, no AI training Townes does not sell your data, use it for advertising, or use it to develop, improve, or train non-personalized AI or machine-learning models.
- Revoke access any time
Run
mail-cli auth logout <account> --yes, or remove access in your Google Account at myaccount.google.com/permissions.
CONTACT
Townes Mail CLI is made by Townes & Co. For questions about the tool or your data, email robert@townes.ai.