GmailSummarizer: AI-Powered Email Intelligence with Spring WebFlux and OpenAI

Introduction

In the age of information overload, email remains one of the most critical communication channels for professionals. The average knowledge worker receives over 120 emails per day, making it increasingly difficult to stay on top of important messages. What if you could leverage AI to automatically summarize your emails, extract key action items, and surface the most important information?

GmailSummarizer is a reactive Spring Boot application that demonstrates how to build a practical GenAI application by combining the Gmail API with OpenAI's language models. This project showcases real-world patterns for OAuth 2.0 authentication, reactive programming with WebFlux, and AI-powered content processing.

Key Insight: The intersection of email APIs and Large Language Models (LLMs) creates powerful opportunities for intelligent email management and productivity enhancement.

Project Overview

GmailSummarizer provides a foundation for building AI-powered email intelligence applications:

• OAuth 2.0 Authentication: Secure Gmail API access using Google's OAuth flow
• Reactive Architecture: Built on Spring WebFlux for non-blocking, scalable email processing
• Email Retrieval: Fetch and filter emails by date range and keywords
• AI Summarization: Integration with OpenAI for generating intelligent email summaries
• Clean REST API: Well-designed endpoints for email search and summarization

Architecture Overview

The application follows a clean, layered architecture that separates concerns and enables scalability:

OAuth 2.0 Authentication Flow

Secure access to Gmail requires implementing the OAuth 2.0 authorization code flow. This ensures users maintain control over their email data while granting the application limited, scoped access.

The Complete OAuth Flow

OAuth Configuration

The application requires Google Cloud Platform credentials configured in application.properties:

# Google OAuth 2.0 Configuration
google.client-id=your-client-id.apps.googleusercontent.com
google.client-secret=your-client-secret
google.redirect-uri=http://localhost:8080/oauth2callback

# Gmail API Scopes
google.scopes=https://www.googleapis.com/auth/gmail.readonly

Key OAuth Concepts

Reactive Email Processing with WebFlux

The application leverages Spring WebFlux to provide non-blocking, reactive email processing. This is particularly important when dealing with potentially large email datasets and external API calls.

Why Reactive?

Traditional blocking I/O creates thread-per-request overhead. When fetching emails and processing them through an AI model, multiple external calls are required. Reactive programming allows:

• Better Resource Utilization: Threads are not blocked waiting for I/O
• Higher Throughput: Handle more concurrent requests with fewer threads
• Backpressure Support: Gracefully handle varying load
• Streaming Responses: Return results as they become available

Reactive Email Service

@Service
public class EmailService {

    private final GmailClient gmailClient;
    private final AISummarizer aiSummarizer;

    public Flux<EmailSummary> getEmailSummaries(
            String userId,
            String keywords,
            LocalDate startDate,
            LocalDate endDate) {

        return gmailClient.fetchEmails(userId, keywords, startDate, endDate)
            .flatMap(email -> aiSummarizer.summarize(email))
            .onErrorResume(e -> {
                log.error("Error processing email", e);
                return Mono.empty();
            });
    }
}

Processing Pipeline

Gmail API Integration

The Gmail API provides programmatic access to Gmail mailboxes. The application uses it to fetch, search, and filter emails.

Email Retrieval Capabilities

The REST API exposes a clean interface for email queries:

# Fetch emails with filters
GET /emails?userId=me&keywords=meeting&startDate=2024-01-01&endDate=2024-01-31

Gmail API Operations

Email Data Model

public record Email(
    String id,
    String threadId,
    String subject,
    String from,
    String to,
    LocalDateTime date,
    String snippet,
    String body,
    List<String> labels
) {}

OpenAI Integration for Email Summarization

The integration with OpenAI transforms raw email content into actionable intelligence. This is where the application delivers real value by extracting meaning from unstructured email text.

AI Summarization Architecture

Prompt Engineering for Email Summarization

Effective prompts are crucial for extracting useful information from emails:

@Component
public class EmailPromptBuilder {

    public String buildSummarizationPrompt(Email email) {
        return """
            Analyze the following email and provide:
            1. A concise 2-3 sentence summary
            2. Key action items (if any)
            3. Urgency level (low/medium/high)
            4. Main topics discussed

            Email Subject: %s
            From: %s
            Date: %s

            Email Body:
            %s

            Respond in JSON format with keys:
            summary, actionItems, urgency, topics
            """.formatted(
                email.subject(),
                email.from(),
                email.date(),
                email.body()
            );
    }
}

AI Summarizer Service

@Service
public class AISummarizer {

    private final OpenAIClient openAIClient;
    private final EmailPromptBuilder promptBuilder;

    public Mono<EmailSummary> summarize(Email email) {
        String prompt = promptBuilder.buildSummarizationPrompt(email);

        return openAIClient.complete(prompt)
            .map(this::parseResponse)
            .map(parsed -> new EmailSummary(
                email.id(),
                email.subject(),
                email.from(),
                parsed.summary(),
                parsed.actionItems(),
                parsed.urgency(),
                parsed.topics()
            ));
    }
}

Summarization Response Model

public record EmailSummary(
    String emailId,
    String subject,
    String from,
    String summary,
    List<String> actionItems,
    String urgency,
    List<String> topics
) {}

Complete Application Flow

The end-to-end flow demonstrates how all components work together:

Getting Started

Prerequisites

• Java 17 or higher
• Maven 3.6+
• Google Cloud Platform account with Gmail API enabled
• OpenAI API key

Installation

# Clone the repository
git clone https://github.com/mgorav/GmailSummarizer.git
cd GmailSummarizer

# Configure credentials
cp application.properties.example application.properties
# Edit application.properties with your credentials

# Build the application
./mvnw clean install

# Run the application
./mvnw spring-boot:run

Configuration

Create your application.properties file:

# Server Configuration
server.port=8080

# Google OAuth 2.0
google.client-id=your-client-id
google.client-secret=your-client-secret
google.redirect-uri=http://localhost:8080/oauth2callback

# OpenAI Configuration
openai.api-key=your-openai-api-key
openai.model=gpt-4
openai.max-tokens=500

# Email Processing
email.batch-size=10
email.max-body-length=4000

Testing

# Run unit tests
./mvnw test

# Run integration tests
./mvnw verify

REST API Reference

Authentication Endpoints

Email Endpoints

Example API Calls

# List emails with keyword filter
curl "http://localhost:8080/emails?userId=me&keywords=project"

# Get AI summary for specific email
curl "http://localhost:8080/emails/abc123/summary"

# Batch summarize recent emails
curl "http://localhost:8080/emails/summarize?days=7&limit=20"

Use Cases and Applications

Personal Productivity

• Daily Digest: Generate a morning summary of overnight emails
• Action Item Extraction: Identify tasks hidden in email threads
• Priority Sorting: AI-powered importance ranking

Business Applications

• Customer Support: Summarize support ticket threads
• Sales Intelligence: Extract key points from prospect communications
• Meeting Prep: Summarize relevant email threads before meetings

Integration Possibilities

Security Considerations

OAuth Token Security

API Key Protection

• Never commit API keys to version control
• Use environment variables or secret management
• Implement rate limiting to prevent abuse
• Log API usage for monitoring

Data Privacy

• Process emails in memory, avoid persistent storage
• Implement data retention policies
• Provide user data export/deletion capabilities
• Consider on-premise OpenAI alternatives for sensitive data

Performance Optimization

Reactive Best Practices

// Good: Non-blocking chain
return gmailClient.fetchEmails(userId)
    .flatMap(email -> aiSummarizer.summarize(email), 5) // Concurrency limit
    .collectList();

// Avoid: Blocking calls
return gmailClient.fetchEmails(userId)
    .map(email -> aiSummarizer.summarize(email).block()); // Anti-pattern!

Caching Strategies

• Cache OAuth tokens (with TTL)
• Cache email metadata (invalidate on webhook)
• Cache AI summaries (with content hash)

Rate Limiting

Conclusion

GmailSummarizer demonstrates how to build practical GenAI applications by combining modern reactive architecture with powerful AI capabilities. The project showcases several important patterns:

• OAuth 2.0 Implementation: Secure, user-controlled API access
• Reactive Programming: Scalable, non-blocking I/O operations
• API Integration: Clean abstractions over external services
• AI/LLM Integration: Practical prompt engineering and response parsing

This architecture can be extended to support additional email providers, alternative AI models, and various output integrations. The reactive foundation ensures the application can scale to handle large email volumes while maintaining responsive performance.

Explore the full source code at github.com/mgorav/GmailSummarizer to see these patterns in action and adapt them for your own AI-powered applications.

Further Reading

• Gmail API Documentation
• Google OAuth 2.0 Guide
• Spring WebFlux Reference
• OpenAI API Documentation
• Project Reactor Documentation
• Prompt Engineering Guide