aerc-google-workspace.md (7220B)
1 --- 2 title: Configuring Aerc to Work with Google Workspace via OAuth2 3 author: Nathaniel Chappelle 4 date: Thu, 12 Feb 2026 21:45:00 -0800 5 --- 6 7 I recently set up aerc with Google Workspace, and like most people attempting 8 this in 2026 I ran straight into the challenges of modern authentication. 9 10 Google no longer allows basic username/password authentication for IMAP and SMTP 11 on most accounts. App passwords are increasingly restricted, especially in 12 managed Workspace environments. If you want your terminal mail client to keep 13 working, you need OAuth2. 14 15 Unfortunately, I couldn't find any guides that were complete and relevant, 16 except for [this one](https://lukaswerner.com/post/2024-07-08@aerc-outlook), 17 ironically written by a student of the same university I attend. This guide was 18 for Office365 emails, but it was a good starting point and pointed me towards 19 the `oauth2` script. 20 21 I wanted a setup that was: 22 23 - Secure (no stored passwords) 24 - Durable (not dependent on someone else’s client ID) 25 - Fully functional for both IMAP and SMTP 26 - Compatible with aerc’s native xoauth2 support 27 28 This post walks through the complete process of registering your own OAuth 29 client in Google Cloud, generating tokens using the OAuth2 script, and 30 configuring aerc to authenticate cleanly with STARTTLS. 31 32 ## Prerequisites 33 34 This guide assumes some certain aspects of your environment: 35 36 - A Linux operating system (I use [Void](https://voidlinux.org/)) 37 - A Python installation (< Python 3.7) 38 - [aerc](https://aerc-mail.org/), a pretty good email client 39 - The 40 [`mutt_ouath2.py`](https://gitlab.com/muttmua/mutt/-/blob/master/contrib/mutt_oauth2.py) 41 script 42 - GPG keys set up (technically optional but super recommended) 43 44 ## Creating OAuth Credentials in Google Cloud 45 46 So our first step is to obtain vaid Google OAuth2 client ID's via the Google 47 Cloud Console. This is pretty simple: 48 49 1. Open the [clients](https://console.cloud.google.com/auth/clients) page of the 50 Google Cloud Console. 51 2. Click the create a client button, and select 'Desktop App' as the application 52 type from the dropdown. 53 3. Give your client a good name (like [jmail](https://jmail.world/)) 54 4. This step is important. When you create the client ID a pop-up will show you 55 your new client-id and client-secret. Make sure to save these in a good 56 place. 57 5. If you created the OAuth2 credentials with your personal Google account, but 58 your work account is the one you're trying to connect with aerc you will have 59 to navigate to the [audience](https://console.cloud.google.com/auth/audience) 60 tab and add your work account as a user. 61 62 Now you have your OAuth2 credentials, and we can move on to configuring aerc and 63 the OAuth2 script. 64 65 ## Configuring the Script 66 67 I would place a copy of the `mutt_oauth2.py` script in your aerc config 68 directory, and then open it with your favorite text editor. Navigate to the 69 Google section of the `registrations` object. It should look something like 70 this: 71 72 ```python 73 'google': { 74 'authorize_endpoint': 'https://accounts.google.com/o/oauth2/auth', 75 'devicecode_endpoint': 'https://oauth2.googleapis.com/device/code', 76 'token_endpoint': 'https://accounts.google.com/o/oauth2/token', 77 'redirect_uri': 'urn:ietf:wg:oauth:2.0:oob', 78 'imap_endpoint': 'imap.gmail.com', 79 'pop_endpoint': 'pop.gmail.com', 80 'smtp_endpoint': 'smtp.gmail.com', 81 'sasl_method': 'OAUTHBEARER', 82 'scope': 'https://mail.google.com/', 83 'client_id': '', 84 'client_secret': '', 85 }, 86 ``` 87 88 Now, I hope it is evident what you should do next, but in case it isn't just 89 copy the `client_id` and `client_secret` you saved earlier into their respective 90 positions within the object. 91 92 Additionally, make sure to input your GPG identity in the encryption and 93 decryption pipe arrays. 94 95 ```python 96 ENCRYPTION_PIPE = ['gpg', '--encrypt', '--recipient', 'you@yourdomain.com'] 97 DECRYPTION_PIPE = ['gpg', '--decrypt'] 98 ``` 99 100 ### Why Is This Important? 101 102 The token file created by mutt_oauth2.py contains your refresh token, which can 103 be used to generate new access tokens without your password or MFA. Because 104 OAuth tokens are bearer credentials, anyone who obtains that file can access 105 your mailbox. Encrypting it with GPG ensures that even if the file is copied, 106 synced, or backed up, it cannot be used without your private key. 107 108 But if you prefer simplicity, you can bypass encryption by replacing the GPG 109 pipes with something like: 110 111 ```python 112 ENCRYPTION_PIPE = ['tee'] 113 DECRYPTION_PIPE = ['cat'] 114 ``` 115 116 This works because the script simply pipes JSON through those commands. However, 117 doing so stores the refresh token in plaintext, meaning security relies entirely 118 on filesystem permissions. 119 120 ## First Time Authentication 121 122 Now you should be ready to create your local tokens. In your aerc configuration 123 directory you can run 124 `python3 mutt_oauth2.py --authorize you@yourdomain.com.tokens`. The script will 125 launch and take you through a interactive menu. It is self-explanatory except at 126 the auth-flow section. Here I chose `authcode` but you will probably be 127 successful with any of the choices. Assuming you chose `authcode`, the script 128 will then give you a url. Open it in a browser and be ready to copy the url 129 you'll be redirected to. Once you get that url, find the section which has 130 `code=` and copy the code. Paste that back into the script and the token file 131 will be created. 132 133 You can test it with `python3 mutt_oauth2.py you@yourdomain.com.tokens --test`. 134 If you don't see any errors you should be good to continue and start configuring 135 aerc. 136 137 ## Configuring aerc 138 139 Aerc uses a very simple toml style configuration. The key aspects we're going to 140 to need to focus on is to use `xoauth2` for our `imaps` and `smtp`, as well as 141 using the `mutt_oauth2.py` script pointed towards the authentication tokens for 142 the `source-cred-cmd`. Here's what my config ended up looking like: 143 144 ```toml 145 [yourdomain] 146 source = imaps+xoauth2://you%40yourdomain.com@imap.gmail.com:993 147 source-cred-cmd = "python3 /home/username/.config/aerc/oauth2.py /home/username/.config/aerc/you@yourdomain.com.tokens" 148 outgoing = smtp+xoauth2://you%40yourdomain.com@smtp.gmail.com:587 149 outgoing-cred-cmd = "python3 /home/username/.config/aerc/oauth2.py /home/username/.config/aerc/you@yourdomain.com.tokens" 150 default = INBOX 151 cache-headers = true 152 from = "Last Name, First Name" <you@yourdomain.com> 153 check-mail = 5m 154 ``` 155 156 Gmail uses implicit TLS for IMAP on port 993 and STARTTLS for SMTP on port 587, 157 both of which are handled automatically by aerc. 158 159 That should be all you need. You can now start aerc and your Google Workspace 160 emails should start loading in. 161 162 ## Conclusion 163 164 Setting up OAuth2 with aerc is more involved than pasting in a password, but it 165 results in a cleaner and more future-proof configuration. 166 167 Once configured, tokens refresh automatically, no passwords are stored in 168 plaintext, and aerc behaves like any other mail client, just faster , more 169 ergonomic, and entirely contained within the terminal. 170 171 Email authentication may be more complex than it used to be, but with the right 172 setup, it doesn’t have to get in the way of a minimal and keyboard-driven 173 workflow.