Cold Mail Generator Service

Purpose and Scope

The Cold Mail Generator Service provides AI-powered personalized cold email generation for job seekers reaching out to recruiters or hiring managers. The service analyzes resume content, incorporates company research, and generates professional email subject lines and body content tailored to the recipient and target company.

This page covers the cold email generation and editing functionality. For interview preparation features, see Hiring Assistant Service. For resume analysis that feeds into this service, see Resume Analysis Service.

Overview

The Cold Mail Generator Service offers two primary capabilities:

1. Email Generation: Creates personalized cold emails from scratch using resume data and recipient information
2. Email Editing: Refines previously generated emails based on user feedback and edit instructions

The service is implemented in two versions:

• V1: Accepts file uploads (PDF, DOCX, TXT) and processes them into resume text
• V2: Accepts pre-processed resume text directly (used when resume is already analyzed)

Both versions leverage Google's Gemini LLM via LangChain prompt chains and optionally integrate company research data to enhance personalization.

Service Architecture

Request and Response Models

ColdMailRequest

The ColdMailRequest model defines the input parameters for cold email generation:

ColdMailResponse

The ColdMailResponse model contains the generated email content:

V1 Service Flow (File Upload)

Email Generation with File Upload

V2 Service Flow (Text-based)

The V2 services skip file processing and operate directly on resume text, making them more efficient when the resume has already been analyzed:

Email Editing Flow

The editing services allow users to refine generated emails by providing specific edit instructions:

The edit chain receives all original parameters plus:

• previous_email_subject: The previously generated subject
• previous_email_body: The previously generated body
• edit_instructions: User's requested changes

Core Generation Logic

generate_cold_mail_content

The generate_cold_mail_content() function is the core logic for email generation:

Input Parameters:

• resume_text: Processed resume content
• recipient_name, recipient_designation, company_name: Recipient details
• sender_name, sender_role_or_goal: Sender details
• key_points_to_include: Achievements to highlight
• additional_info_for_llm: Extra context
• company_research: Research data from web search

Process:

1. Invokes cold_main_generator_chain with all parameters
2. Receives LLM response (various formats possible)
3. Parses JSON to extract subject and body fields
4. Returns dictionary with email content

generate_cold_mail_edit_content

Similar to generation but includes edit-specific parameters:

Additional Parameters:

• previous_email_subject: Original subject line
• previous_email_body: Original email body
• edit_instructions: User's requested changes

Uses cold_mail_edit_chain instead of the generation chain.

Response Parsing Strategy

The service implements a robust JSON parsing strategy to handle various LLM response formats:

Handled Formats:

1. Pure JSON: {"subject": "...", "body": "..."}
2. Markdown Code Block: ```json\n{...}\n```
3. Mixed Content: Text containing JSON delimiters {...}

This multi-strategy approach ensures robustness against various LLM output formats.

Company Research Integration

The service optionally enriches email generation with company research data:

The get_company_research() function:

1. Takes company name and URL
2. Uses Web Content Agent to extract website content
3. Returns summarized company information
4. Data is passed to LLM for context-aware email generation

File Processing Pipeline (V1 Only)

File Handling Details:

• Temporary files saved to backend/uploads/temp_cold_mail_{filename}
• process_document() extracts text based on file type
• LLM formatting applied only to PDF/DOCX (not MD/TXT)
• Files deleted after processing to avoid storage buildup

Error Handling

The service implements comprehensive error handling:

All errors return ErrorResponse model with descriptive messages.

Error Response Format:

ErrorResponse(
    success=False,
    message="Error description",
    error_detail="Detailed error info"
)

LLM Integration

Prompt Chains

The service uses two LangChain prompt chains:

1. cold_main_generator_chain: Main email generation
2. cold_mail_edit_chain: Email editing/refinement

Both chains are imported from the app.data.prompt module and invoke Google Gemini via the shared llm instance.

Chain Invocation:

response = cold_main_generator_chain.invoke({
    "resume_text": resume_text,
    "recipient_name": recipient_name,
    "recipient_designation": recipient_designation,
    "company_name": company_name,
    "sender_name": sender_name,
    "sender_role_or_goal": sender_role_or_goal,
    "key_points_to_include": key_points_to_include,
    "additional_info_for_llm": additional_info_for_llm,
    "company_research": company_research,
})

LLM Configuration

The service uses the shared LLM instance from app.core.llm:

• Model: gemini-2.0-flash (via ChatGoogleGenerativeAI)
• Temperature: 0.1 (for consistent, focused output)
• Provider: Google Generative AI

Service Comparison Table

Dependencies

The Cold Mail Generator Service depends on:

Usage Patterns

Pattern 1: Generate from Previously Analyzed Resume

When a resume has already been analyzed (stored in database), use V2:

1. Fetch resume text from database
2. Call cold_mail_generator_v2_service() with text
3. Return generated email to frontend
4. Frontend can save to database or allow editing

Pattern 2: Generate from New Upload

When user uploads a new resume file, use V1:

1. Accept file upload
2. Call cold_mail_generator_service() with file
3. Service processes, validates, and generates
4. Return email content

Pattern 3: Iterative Refinement

For editing generated emails:

1. User reviews generated email
2. Provides edit instructions (e.g., "make it shorter", "add more technical details")
3. Call cold_mail_editor_v2_service() with original params + edit instructions
4. Service generates refined version
5. Can repeat until satisfied