Gmail setup and troubleshooting
Gmail connection requires a Google OAuth client ID and secret from the same Google Cloud project where the Gmail API is enabled.
Set up Google Cloud
- Enable the Gmail API in the Google Cloud project that owns the OAuth client.
- Create an OAuth client with application type Desktop app in Google Cloud Console.
- Set
HAFI_GMAIL_CLIENT_IDandHAFI_GMAIL_CLIENT_SECRETfrom that client in the environment where Hafi will run. - Connect using
bun run dev connect gmail --account personalwhile running from source.
Hafi listens on 127.0.0.1 using a random available port for the browser callback. Do not register a fixed redirect URI for a Desktop app client.
Add a test user while the OAuth app is in Testing
Open Google Auth Platform > Audience and add the exact Google account you will authorize under Test users. Use that account in the browser when running bun run dev connect gmail.
While the OAuth app remains in Testing, Google expires this authorization and its refresh token after seven days. Reconnect when authorization expires to continue scheduled use.
Troubleshoot
| Error or symptom | Cause and resolution |
|---|---|
redirect_uri_mismatch |
A Web application client expects a fixed redirect URI. Create and use a Desktop app client from the same project instead. |
Error 403: access_denied / available only to developer-approved testers |
Add the exact account to Test users under Google Auth Platform > Audience, then authorize with that account. |
| Authorization stops working after several days | Testing-mode authorizations expire after seven days. Reconnect, or review the OAuth app’s publishing and verification requirements with Google before production use. |
| Gmail API request fails | Confirm the Gmail API is enabled in the project owning the OAuth client, and that the ID and secret both belong to that project. |
Live Gmail account behavior and permissions still require end-to-end verification. See Getting started for the full setup sequence.