Outlook Integration Architecture

The Microsoft Outlook integration is a critical component of the Trackr SaaS platform, enabling automated job application tracking by seamlessly connecting with users' email accounts. By integrating directly with the Microsoft Graph API, Trackr can monitor, parse, and synchronize job-related communications, providing users with a unified, real-time dashboard of their job search progress without requiring manual data entry.

This document details the technical architecture, authorization workflows, data synchronization strategies, and security protocols that underpin the Trackr Outlook integration.

OAuth 2.0 Authorization Flow

Trackr utilizes the industry-standard OAuth 2.0 protocol with the Authorization Code grant type to securely obtain access to user data. This flow ensures that Trackr never handles or stores user passwords. Instead, it relies on Microsoft's secure authentication infrastructure.

When a user initiates the connection to their Outlook account, the following sequence of events occurs:

sequenceDiagram
    participant User
    participant Trackr Client
    participant Trackr Backend
    participant Microsoft Entra ID
    participant Microsoft Graph API
 
    User->>Trackr Client: Clicks "Connect Outlook"
    Trackr Client->>Microsoft Entra ID: Redirects with Client ID, scopes, and redirect URI
    Microsoft Entra ID->>User: Prompts for authentication & consent
    User->>Microsoft Entra ID: Authenticates and grants permissions
    Microsoft Entra ID->>Trackr Client: Redirects back with Authorization Code
    Trackr Client->>Trackr Backend: Sends Authorization Code
    Trackr Backend->>Microsoft Entra ID: Exchanges Code for Access & Refresh Tokens (with Client Secret)
    Microsoft Entra ID->>Trackr Backend: Returns Access Token & Refresh Token
    Trackr Backend->>Trackr Backend: Encrypts and stores Refresh Token in secure vault
    Trackr Backend->>Microsoft Graph API: Makes initial API request with Access Token
    Microsoft Graph API->>Trackr Backend: Returns requested data (e.g., user profile)
    Trackr Backend->>Trackr Client: Confirms successful connection
    Trackr Client->>User: Displays success message

Token Management and Rotation

The access tokens issued by Microsoft Entra ID (formerly Azure Active Directory) are short-lived, typically expiring in one hour. To maintain persistent access without requiring constant user re-authentication, Trackr securely stores the long-lived refresh token.

Our token management service proactively monitors access token validity. When a background synchronization task initiates, the service first checks the expiration of the current access token. If the token has expired or is within five minutes of expiration, the service uses the refresh token to request a new access token pair. This seamless token rotation is crucial for the reliability of our background processing pipeline. If a refresh token is ever revoked by the user or expires due to prolonged inactivity (typically 90 days), the system generates a notification prompting the user to re-authorize the connection.

Permissions and Scopes

Adhering to the principle of least privilege, Trackr requests only the specific OAuth scopes absolutely necessary for its core functionality. We do not request full mailbox access, ensuring user privacy and minimizing the potential impact of any security incidents.

The integration relies on the following Microsoft Graph API scopes:

User.Read: Required for basic profile information. We use this scope to identify the user and link the Outlook account to the corresponding Trackr account. This includes reading the user's primary email address and display name.
Mail.Read: This is the core scope that permits reading the contents of the user's mailbox. It is essential for searching and retrieving emails related to job applications, interviews, and offers. Note that this scope is strictly read-only; Trackr cannot modify, delete, or send emails on the user's behalf.
offline_access: This scope is necessary to receive a refresh token during the initial authorization flow. It allows Trackr to maintain access and perform background synchronization even when the user is not actively logged into the Trackr application.

By restricting our access to these specific read-only scopes, we build trust with our users and simplify our compliance posture.

Data Synchronization Architecture

The synchronization engine is the heart of the Outlook integration. It is responsible for continuously monitoring the connected mailbox, identifying relevant emails, and updating the Trackr database in near real-time. The architecture is designed to be highly scalable, fault-tolerant, and efficient, minimizing API calls and respecting Microsoft Graph's rate limits.

Initial Full Sync Process

Upon successful authorization, Trackr initiates a comprehensive historical sync. This process scans the user's inbox to identify past job applications and build an initial baseline for the user's dashboard.

Because an inbox can contain tens of thousands of emails, a brute-force scan is impractical. Instead, we utilize the robust search capabilities of the Microsoft Graph API. The initial sync executes a series of targeted search queries using keywords and patterns commonly associated with recruitment processes (e.g., "application received," "interview invitation," "offer letter," common Applicant Tracking System (ATS) domains).

The initial sync is executed asynchronously in the background. We utilize pagination (using the @odata.nextLink property provided by the Graph API) to retrieve large result sets reliably. To handle potential network interruptions or API throttling, the sync job maintains its state. If a failure occurs, the job can resume from the last successfully processed page, ensuring data completeness without redundant processing.

Incremental Sync via Delta Queries

Following the initial sync, Trackr shifts to an incremental synchronization model to maintain an up-to-date view of the user's job search. Relying on repeated full scans would be computationally expensive and would likely trigger API rate limits. Instead, we leverage Microsoft Graph's Delta Query functionality.

Delta queries allow our system to request only the changes (additions, updates, and deletions) that have occurred in a specific mail folder since the last synchronization.

sequenceDiagram
    participant Trackr Sync Engine
    participant Trackr Database
    participant Microsoft Graph API
 
    Trackr Sync Engine->>Trackr Database: Retrieve latest Delta Token for User
    Trackr Database-->>Trackr Sync Engine: Return Delta Token (or null if first run)
    
    alt First Incremental Sync (No Token)
        Trackr Sync Engine->>Microsoft Graph API: GET /me/mailFolders/inbox/messages/delta
    else Subsequent Sync (Token Exists)
        Trackr Sync Engine->>Microsoft Graph API: GET /me/mailFolders/inbox/messages/delta?$deltatoken={token}
    end
    
    Microsoft Graph API-->>Trackr Sync Engine: Return Changed Messages & New Delta Token (or NextLink)
    
    loop While NextLink exists
        Trackr Sync Engine->>Trackr Database: Process & Store Messages (Parse, Dedup, etc.)
        Trackr Sync Engine->>Microsoft Graph API: GET {NextLink}
        Microsoft Graph API-->>Trackr Sync Engine: Return Changed Messages & New Delta Token (or NextLink)
    end
    
    Trackr Sync Engine->>Trackr Database: Store new Delta Token for future use
    Trackr Database-->>Trackr Sync Engine: Confirmation

The incremental sync process runs on a scheduled basis (e.g., every 15 minutes) for active users. The workflow is as follows:

Retrieve Token: The synchronization engine retrieves the last saved Delta Token for the user from our secure database.
API Request: A request is made to the Graph API's /delta endpoint, passing the Delta Token.
Process Changes: The Graph API returns a collection of messages that have changed. Our engine processes these messages, passing them through the parsing logic (detailed below) to determine relevance.
Update State: Along with the changed messages, the Graph API provides a new Delta Token. This token is saved to the database, representing the new baseline for the next synchronization cycle.

This approach minimizes bandwidth, reduces API load, and ensures that Trackr reflects the latest updates almost immediately.

Email Parsing Logic

Retrieving emails is only the first step; the true value of Trackr lies in its ability to intelligently interpret the contents of those emails. Our parsing engine uses a combination of heuristics, regular expressions, and machine learning models to extract structured data from unstructured text.

Not all emails in an inbox are relevant to a job search. The parsing engine first applies a series of filters to identify potential candidate emails:

Sender Analysis: We maintain a comprehensive, continually updated database of known ATS domains (e.g., greenhouse.io, lever.co, workday.com, myworkday.com, icims.com). Emails originating from these domains are immediately flagged for deeper analysis. We also analyze the "Reply-To" headers, which often reveal the true origin of an email even if it was sent via a generic corporate address.
Subject Line Heuristics: The system scans subject lines for high-confidence keywords such as "Application," "Interview," "Offer," "Next Steps," "Candidate," and "Rejection." Natural Language Processing (NLP) is used to contextualize these keywords to minimize false positives (e.g., distinguishing between an "application received" for a job versus a software application update).
Content Classification: For emails that pass the initial sender and subject filters, the engine performs a lightweight classification of the email body to confirm its relevance.

Extracting Metadata

Once an email is confirmed as job-related, the extraction pipeline isolates specific metadata to populate the user's dashboard.

Company Name: We extract the company name primarily from the sender's domain, cross-referencing it with a database of corporate entities. For agency recruiters, we attempt to parse the client company name from the email body using Named Entity Recognition (NER).
Job Title: Subject lines and email bodies are analyzed to identify the specific role. We look for patterns like "regarding your application for [Title]" or "[Title] - Interview."
Application Stage: This is the most complex extraction task. We categorize emails into distinct stages: Applied, Interviewing, Offer, and Rejected.
- Applied: Triggered by phrases like "Thank you for applying," "Application received."
- Interviewing: Triggered by "invitation to interview," "schedule a time," calendar attachments (.ics files).
- Offer: Triggered by "Congratulations," "Offer details," "Compensation package."
- Rejected: Triggered by "Unfortunately," "Pursuing other candidates," "Not a fit at this time."
Dates and Deadlines: We extract interview dates, times, and offer expiration deadlines from the text and metadata, enabling calendar integration and reminders within the Trackr platform.

The parsing engine is designed to be resilient to the highly varied formatting used by different companies and tracking systems. It is continuously trained on new data to improve its accuracy and handle edge cases.

Duplicate Detection Mechanism

Because a single job application process generates multiple emails (confirmation, multiple interview rounds, offer), it is critical to group these communications accurately. Failing to do so would result in a fragmented and confusing dashboard for the user. Our duplicate detection and clustering mechanism ensures a clean, unified view.

When a new relevant email is processed, the system attempts to associate it with an existing job application record using a multi-factor matching algorithm:

Thread ID Matching: This is the most reliable method. If the new email is part of an existing conversation thread (determined by the conversationId property provided by the Graph API), it is immediately linked to the application associated with that thread.
Company and Title Correlation: If the email is a new thread, the system searches the user's existing records for an application with the same company name and job title within a reasonable timeframe (e.g., the last 90 days).
Sender Domain Clustering: If the job title is missing or ambiguous, but the sender domain and company match an active application, the system may cluster the email based on a calculated confidence score.
Manual Override: Despite robust automation, edge cases exist. The Trackr interface allows users to manually merge or split application records if the system's clustering is inaccurate.

By employing these layered techniques, we prevent the creation of duplicate application entries and ensure that the entire narrative of a specific job opportunity is consolidated in one place.

Security and Compliance

Handling email data requires the highest level of security and a strong commitment to privacy. The Trackr Outlook integration is built on a foundation of robust security practices designed to protect user data at every stage of the lifecycle.

Data Encryption

In Transit: All communication between the Trackr Client, Trackr Backend, and the Microsoft Graph API is encrypted using TLS 1.2 or higher. We employ strict transport security policies to prevent interception or tampering.
At Rest: Sensitive data, notably OAuth refresh tokens and the extracted metadata (company names, job titles, communication snippets), is encrypted at rest within our database infrastructure using AES-256 encryption. We utilize a secure key management service to handle encryption keys, ensuring that access to the data is strictly controlled.

Least Privilege and Data Minimization

As detailed in the Permissions section, we request only the Mail.Read scope. We do not have the ability to send emails or modify the user's inbox in any way. Furthermore, we practice strict data minimization. We do not store the full body of every email. We extract only the necessary metadata (sender, date, extracted job title, company, stage) required to drive the Trackr dashboard. The raw email content is processed in memory and immediately discarded, significantly reducing our data footprint and minimizing risk in the event of a breach.

Infrastructure and Auditing

The backend services that handle synchronization and parsing operate within isolated, secure network segments. Access to these systems is heavily restricted and requires multi-factor authentication. We maintain comprehensive audit logs of all system activities, including token rotation, synchronization events, and access to sensitive data. These logs are continuously monitored by automated intrusion detection systems to identify and respond to any anomalous behavior.

Compliance Standards

Our security architecture is designed to comply with major privacy regulations, including the General Data Protection Regulation (GDPR) and the California Consumer Privacy Act (CCPA). Users maintain full ownership of their data and can revoke Trackr's access to their Outlook account at any time. Upon revocation, we immediately delete all associated OAuth tokens and provide automated mechanisms for users to request the deletion of their parsed application data from our systems. Regular independent security audits and penetration testing are conducted to validate the effectiveness of our security controls and ensure ongoing compliance.

Conclusion

The Trackr Outlook integration provides a seamless, powerful mechanism for automating job search tracking. By combining secure OAuth 2.0 authorization, efficient Delta Query synchronization, advanced natural language parsing, and robust security protocols, we deliver a reliable service that significantly reduces the administrative burden on our users. This architecture allows users to focus on the content of their applications rather than the mechanics of tracking them, fulfilling Trackr's core mission of simplifying the job search process.

Outlook Integration