Trackr

Gmail Integration

OAuth, synchronization, and security for the Trackr Gmail integration.

Gmail Integration for Trackr

The Trackr Gmail integration allows users to seamlessly synchronize their job application emails, interview schedules, and recruiter communications directly into their Trackr dashboard. This document provides a comprehensive overview of the integration's architecture, including OAuth authentication, permissions, incremental synchronization strategies, email parsing logic, duplicate detection mechanisms, and security considerations.

Overview

Integrating Gmail into Trackr provides a frictionless experience for job seekers. Instead of manually entering data for every application, Trackr connects to the user's Gmail account, intelligently identifies emails related to job applications, and automatically updates the status of each job in the pipeline.

This integration is built with privacy and security as the foremost priorities. Trackr only requests the minimum necessary permissions, employs robust parsing logic to avoid collecting irrelevant data, and utilizes Google's official APIs and best practices.

OAuth and Authentication Flow

The foundation of the Gmail integration is the OAuth 2.0 protocol. Trackr acts as a third-party application requesting access to the user's Gmail account on their behalf. We use the standard Authorization Code flow.

OAuth Sequence Diagram

Here is a sequence diagram illustrating the OAuth flow:

sequenceDiagram
    participant User
    participant Trackr App
    participant Trackr Backend
    participant Google OAuth Server
 
    User->>Trackr App: Clicks "Connect Gmail"
    Trackr App->>Trackr Backend: Request OAuth Authorization URL
    Trackr Backend-->>Trackr App: Return Google OAuth URL
    Trackr App->>User: Redirect to Google Login
    User->>Google OAuth Server: Authenticate and Approve Scopes
    Google OAuth Server-->>Trackr App: Redirect with Authorization Code
    Trackr App->>Trackr Backend: Send Authorization Code
    Trackr Backend->>Google OAuth Server: Exchange Code for Tokens (Client ID, Secret)
    Google OAuth Server-->>Trackr Backend: Return Access & Refresh Tokens
    Trackr Backend->>Trackr Backend: Securely store Refresh Token
    Trackr Backend-->>Trackr App: Gmail Integration Successful
    Trackr App->>User: Show Success Message

Authorization Process Detailed

  1. Initiation: The user initiates the connection from their Trackr settings page.
  2. Redirection: Trackr redirects the user to Google's consent screen. This screen clearly outlines the specific permissions Trackr is requesting.
  3. Consent: The user reviews the requested scopes and grants permission.
  4. Token Exchange: Google returns a short-lived authorization code to Trackr's backend. The backend securely exchanges this code for an Access Token and a Refresh Token.
  5. Token Storage: The Access Token is used for immediate API requests, while the Refresh Token is securely stored (encrypted at rest) in Trackr's database. The Refresh Token allows Trackr to obtain new Access Tokens when the current one expires, enabling continuous synchronization without requiring the user to log in again.

Permissions and Scopes

Trackr adheres strictly to the principle of least privilege. We only request the exact permissions required to fulfill the integration's promise: reading emails related to job applications.

Requested Scopes

  • https://www.googleapis.com/auth/gmail.readonly: This is the primary scope required. It grants Trackr read-only access to the user's emails. Trackr cannot send, delete, or modify any emails.

Scope Justification and Review

Google requires a rigorous verification process for any application requesting the gmail.readonly scope, as it is considered a restricted scope. Trackr has undergone and passed this verification process, which includes a third-party security assessment. This ensures that our systems are designed to handle sensitive user data securely. We continuously monitor our usage to ensure we never overstep these boundaries.

Incremental Synchronization Strategy

To ensure a responsive user experience and respect API rate limits, Trackr employs an incremental synchronization strategy. We do not download the user's entire mailbox. Instead, we use Google's History API to only fetch what has changed since the last sync.

Initial Sync

When a user first connects their Gmail account, Trackr performs an initial synchronization.

  1. Querying: We use specific query parameters (e.g., subject:("application" OR "interview" OR "offer") AND (from:(*@workday.com OR *@greenhouse.io OR *@lever.co))) to retrieve only the most likely relevant emails from the past 6 months.
  2. History ID: Upon completing the initial sync, Trackr stores the current historyId provided by the Gmail API.

Incremental Sync Flow

For all subsequent syncs, Trackr uses the stored historyId.

sequenceDiagram
    participant Trackr Worker
    participant Gmail API
    participant Database
 
    Trackr Worker->>Database: Retrieve last known historyId
    Trackr Worker->>Gmail API: Request history (startHistoryId=last_id)
    Gmail API-->>Trackr Worker: Return list of changed messages (added, deleted, labels)
    Trackr Worker->>Trackr Worker: Filter for "messageAdded" events
    loop For each added message
        Trackr Worker->>Gmail API: Fetch full message content (Format: RAW or FULL)
        Gmail API-->>Trackr Worker: Return message data
        Trackr Worker->>Trackr Worker: Parse and process email
    end
    Trackr Worker->>Database: Update stored historyId

Webhooks (Push Notifications)

To provide near real-time updates, Trackr integrates with Gmail Push Notifications via Google Cloud Pub/Sub.

  1. Trackr subscribes to notifications for the user's mailbox.
  2. When a new email arrives, Google publishes a message to Trackr's Pub/Sub topic.
  3. The message contains the user's email address and a new historyId.
  4. Trackr's workers process this notification, triggering the incremental sync flow described above.

This combination of webhooks and incremental polling ensures that Trackr is always up-to-date without aggressively polling the API.

Email Parsing and Extraction Logic

The core value of the Trackr Gmail integration lies in its ability to accurately understand the content of emails and extract structured data. This is achieved through a multi-tiered parsing engine.

Data Extraction Goals

The parsing engine aims to extract the following information from relevant emails:

  • Company Name: The organization the user applied to.
  • Role/Job Title: The specific position.
  • Status Update: Identifying whether the email is a generic confirmation, an interview invitation, a rejection, or an offer.
  • Dates: Application dates, interview times.
  • Key Contacts: Recruiter names and email addresses.

Parsing Tiers

  1. Sender and Domain Analysis: The first tier looks at the sender. We maintain a database of common Applicant Tracking Systems (ATS) like Greenhouse, Lever, Workday, and Ashbee. If the email originates from one of these known domains, we apply specific templates.
  2. Subject Line Heuristics: The subject line provides strong signals. Regular expressions are used to match patterns like "Your application to [Company]", "Interview Invitation: [Role]", or "Update on your candidacy".
  3. Body Text Natural Language Processing (NLP): If the email doesn't match known ATS templates, we employ NLP techniques. We use Named Entity Recognition (NER) to identify companies, job titles, and dates within the email body. Sentiment analysis and keyword matching (e.g., "unfortunately", "moving forward", "schedule a time") help determine the status update.

Handling HTML and Plain Text

Emails can be complex, often containing multi-part MIME structures with both HTML and plain text representations. Trackr's parser prioritizes the plain text version when available, as it is easier to parse reliably. If only HTML is present, we use robust libraries (like BeautifulSoup or Cheerio) to strip tags and extract the visible text before applying our NLP models.

Duplicate Detection and Idempotency

Because emails can be forwarded, replied to, or sometimes re-delivered by the API in edge cases, Trackr must have robust duplicate detection to prevent creating duplicate job entries or status updates.

Hashing and Fingerprinting

Every email processed by Trackr generates a unique fingerprint. This fingerprint is a cryptographic hash (e.g., SHA-256) of critical email components:

  • Message-ID header (provided by Gmail)
  • Sender address
  • Subject line (normalized)
  • A simplified hash of the body text

Idempotency Checks

Before inserting any new data into the database, Trackr checks for the existence of this fingerprint.

  1. Job Level: Does this email relate to a job we are already tracking? We try to match the Company Name and Role. If a match is found, we link the email to the existing job rather than creating a new one.
  2. Event Level: Have we already processed this specific status update? For example, if a user receives a reminder email for an interview they already scheduled, we shouldn't create a second "Interview Scheduled" event. We track the Message-ID of all processed emails to ensure we handle each specific message exactly once.

By enforcing idempotency at the database level (using unique constraints where appropriate), we guarantee the integrity of the user's tracking data.

Security and Privacy Considerations

Handling users' email data is a massive responsibility. Trackr's architecture is designed to minimize risk and protect user privacy at every stage.

Data Minimization

We only extract and store the specific data points required for the Trackr application (Company, Role, Status, Dates). We do not store the full, raw body of the emails in our persistent databases after the parsing process is complete. Once the relevant metadata is extracted, the raw text is discarded from memory.

Encryption

  • In Transit: All communication between the Trackr app, our backend servers, and Google's APIs happens over TLS 1.2 or higher (HTTPS).
  • At Rest: Sensitive data stored in our databases, particularly the OAuth Refresh Tokens, are encrypted at rest using industry-standard AES-256 encryption. The encryption keys are managed securely via a dedicated Key Management Service (KMS).

Access Control

Access to the production environment and the databases containing user data is strictly limited to authorized personnel on a need-to-know basis. All access is logged and audited.

Revocation and Deletion

Users have complete control over their integration.

  1. Disconnecting: Users can disconnect their Gmail account at any time from the Trackr settings. When they do, Trackr immediately revokes the OAuth token with Google and deletes the Refresh Token from our database.
  2. Data Deletion: When a user deletes their Trackr account, all associated data, including the parsed email metadata, is permanently purged from our systems in accordance with our data retention policy and GDPR/CCPA requirements.

Third-Party Audits

To maintain our access to the gmail.readonly scope, Trackr undergoes mandatory annual security assessments conducted by Google-approved third-party security firms. These audits verify our compliance with Google's API Services User Data Policy, ensuring that our security posture remains strong against evolving threats.

Conclusion

The Trackr Gmail integration is a complex but powerful feature that significantly reduces the friction of tracking job applications. By leveraging OAuth for secure authentication, employing intelligent incremental sync strategies, utilizing advanced parsing logic, and maintaining a strict focus on security and privacy, Trackr provides a seamless and reliable experience for its users while safeguarding their sensitive data. This robust architecture ensures that users can focus on what matters most: preparing for their interviews and landing their dream job.