Gmail Integration
Google OAuth, MIME generation, and Pub/Sub webhook synchronization.
The integrations-google feature slice powers the core outreach engine. It owns the Google OAuth flow, raw MIME building for attachments, and the asynchronous webhook sync.
Architectural Naming
integrations-google rather than nested as integrations/google. This enforces a flat architecture, ensuring that every zone glob and public-API path stays exactly one level deep.Token Encryption (At-Rest)
When a user connects their Gmail account, the system creates a GoogleAccount row. Both the refresh token and the access token are encrypted at rest using AES-256-GCM (via the TOKEN_ENCRYPTION_KEY environment variable).
The 20260803 Migration
accessToken remained plaintext. However, an access token carries the full grant (gmail.send + gmail.readonly) for up to an hour. A database dump could have allowed an attacker to read live mailboxes without needing to decrypt the refresh token. The 20260803 migration fixed this vulnerability by encrypting both.Sending & MIME Construction
Unlike simple transactional emails, job outreach requires sending PDF resumes as attachments. The slice bypasses high-level abstractions and uses the googleapis package to construct and send raw Base64URL-encoded MIME messages natively. Because it routes through the Gmail API, sent emails are automatically placed in the user's actual "Sent" folder.
Pub/Sub Webhook Syncing
To track incoming replies, the platform relies on Google Cloud Pub/Sub. When the user's mailbox changes, Google fires a webhook payload to the system.
The GoogleAccount model tracks the historyId (a cursor for Gmail changes) and the watchExpiration timestamp. This allows the background cron job to incrementally fetch only the latest thread updates and synchronize them down into the platform's EmailMessage table.