Gmail and Google Workspace
Connect a Gmail or Google Workspace account, how labels map to Airpost, and what Gmail-only features do.
Gmail and Google Workspace (G Suite) accounts sign in through your browser with OAuth. Airpost never sees your Google password, and one sign-in covers mail, calendars and contacts.
Connect the account
Choose Gmail or G Suite
On the Connect an email account screen, pick Gmail or G Suite.
Sign in with Google in your browser
Airpost opens Google’s sign-in page in your default browser. Sign in and allow access. If the page doesn’t open, Airpost shows the URL with a copy button so you can paste it into your browser yourself.
Wait for the account to be added
Google redirects back to Airpost on your own machine. Airpost shows “Successfully connected to Google!” and adds the account. Mail starts syncing right away; calendars and contacts follow a few seconds later.
What Airpost asks Google for
The sign-in requests these scopes, and nothing else:
| Scope | Used for |
|---|---|
https://mail.google.com/ | Reading, sending and organizing mail over IMAP and SMTP. |
userinfo.email, userinfo.profile | Your address and name for the account. |
auth/contacts | Syncing contacts and contact groups through the Google People API. |
auth/calendar | Syncing calendars over Google’s CalDAV endpoint. |
The engine stores the refresh token in your OS keychain (see Accounts) and exchanges it for short-lived access tokens as needed. When Google rotates the refresh token, the engine saves the new one.
Builds of Airpost ship with a Google OAuth client. If you build from source or self-host, you can use your own by setting AIRPOST_GMAIL_CLIENT_ID and AIRPOST_GMAIL_CLIENT_SECRET in the engine’s environment. Accounts added with the built-in client keep refreshing through it.
How labels work
Gmail is not a folder-based server, and Airpost treats it differently from other IMAP accounts:
- Every message lives in exactly one of All Mail, Spam or Trash. Labels (including Inbox, Starred and Important) are tags on top of that, read from Gmail’s
X-GM-LABELSextension. - Airpost syncs All Mail rather than every label folder, so a message with five labels is downloaded once, not five times.
- Archiving removes the Inbox label. Moving to a label replaces the thread’s labels with that one, as Gmail’s Move to does. Deleting moves to Trash.
- Labels you create in Airpost are Gmail labels and show up in Gmail on the web, and the other way round.
Apply labels with l (Gmail shortcut set) or Thread > Apply Label, and give a label its own colour by right-clicking it in the sidebar.
# The same from the CLI
airpost labels # list labels
airpost label create "Receipts" --account you@gmail.com
airpost label add "Receipts" <thread-id>
airpost label add "Receipts" -q "from:billing@example.com" --dry-run
airpost archive -q "in:Receipts before:2026-01-01" # takes them out of the inbox
--dry-run lists the threads a query would touch without changing anything. See CLI commands.
Gmail-only features
| Feature | Where | What it does |
|---|---|---|
| Show Gmail-style important markers | Preferences > Reading | Shows Gmail’s importance marker on messages Gmail flags as important. |
| Mark as important / not important | + / - (Gmail shortcut set) | Adds or removes Gmail’s Important label. |
| Remove from view | y (Gmail shortcut set) | Takes the thread out of the label or view you’re in, like Gmail’s y. |
| Rule actions | Rules | Apply Label, Move to Label, Archive and Mark as Important. |
Select the Gmail shortcut set in Preferences > Shortcuts. See Keyboard shortcuts.
Calendar and contacts
Google calendars sync over CalDAV at https://apidata.googleusercontent.com/caldav/v2/<your address>, and contacts and contact groups through the Google People API, using the same sign-in. Calendars refresh about every 15 minutes and contacts about every 75 minutes; the slower contact cadence keeps Airpost inside Google’s API quotas. See Calendar and contacts.
Google Workspace accounts
Workspace accounts sign in the same way. Your Workspace admin controls whether third-party apps can access Gmail. If sign-in ends with an error saying the app is blocked or needs admin approval, the admin has to allow Airpost in the Google Admin console. Nothing in Airpost can work around that.
If sign-in stops working
If Google revokes the token, you change your password, or you remove Airpost’s access in your Google account settings, the account shows “Airpost can’t sign in” in Preferences > Accounts. Click Reconnect or Sign in again… to repeat the browser sign-in, or run:
airpost account reauth you@gmail.com
The engine tests the new token before replacing the old one, so a failed sign-in leaves the account as it was.
Removing a Gmail account (in the app or with airpost account remove) also revokes Airpost’s grant at Google, so it disappears from your Google account’s list of connected apps.