LeadMailer

An AI-powered email outreach automation system built with PortiaAI SDK, FastAPI backend, and React frontend.

Features

• AI-Powered Research: Automatically researches companies using Tavily API
• Personalized Email Generation: Creates customized emails using OpenAI's LLM
• Gmail Integration: Sends emails directly through Gmail with OAuth authentication
• File Processing: Supports PDF resume extraction, CSV lead import, and text files
• Real-time Updates: Live progress tracking via Server-Sent Events (SSE)
• Authentication Flow: Handles OAuth redirects seamlessly for Gmail access

Architecture

Backend (FastAPI + PortiaAI)

• PortiaAI Agent: Orchestrates the entire email outreach workflow
• File Processing: Extracts text from PDFs, parses CSV files
• Session Management: Tracks processing states and real-time updates
• SSE Streaming: Provides live updates to the frontend
• OAuth Handling: Manages Gmail authentication through PortiaAI

Frontend (React)

• Modern UI: Dark-themed interface with gradient styling
• Real-time Updates: Live progress tracking during processing
• File Upload: Drag-and-drop support for attachments
• Authentication: Seamless OAuth redirect handling
• Responsive Design: Works on desktop and mobile devices

Setup Instructions

Prerequisites

1. API Keys Required:
   • PortiaAI API Key (from PortiaAI)
   • OpenAI API Key (from OpenAI)
   • Tavily API Key (from Tavily)

Backend Setup

1. Navigate to backend directory:

   cd backend

2. Install dependencies:

   pip install -r requirements.txt

3. Create environment file:

   cp .env.example .env

4. Configure environment variables in .env:

   # Required
   PORTIA_API_KEY=your_portia_api_key_here
   OPENAI_API_KEY=your_openai_api_key_here
   TAVILY_API_KEY=your_tavily_api_key_here
   

5. Start the backend server:

   uvicorn server:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   yarn install

3. Set API URL (optional, defaults to localhost:8000):

   echo "REACT_APP_API_URL=http://localhost:8000" > .env

4. Start the development server:

   yarn start

5. Open the application: Navigate to http://localhost:3000

Usage

Basic Email Outreach

1. Enter Lead Information:

   • Add lead details in the text area (emails, company names, etc.)
   • Optionally provide additional context
   • Enter your email for authentication

2. Upload Attachments (optional):

   • Resume (PDF)
   • Lead lists (CSV)
   • Additional context (TXT)

3. Start Processing:

   • Click "Start AI Email Outreach"
   • Watch real-time progress updates

4. Authentication (when prompted):

   • Click the Gmail authentication link
   • Grant necessary permissions
   • Return to the application (processing will resume)

5. Review Results:

   • View the completion summary
   • Check final outputs and plan execution details

API Endpoints

The backend provides the following main endpoints:

• POST /api/process-leads - Start email outreach processing
• GET /api/status/{session_id} - Stream real-time updates (SSE)
• GET /api/session/{session_id} - Get session status
• POST /api/upload-files - Upload and process files
• POST /api/resolve-clarification - Resolve user input clarifications
• DELETE /api/session/{session_id} - Cleanup session

How it Works

PortiaAI Integration

The system uses PortiaAI as the orchestration layer:

1. Plan Generation: Creates dynamic execution plans based on user input
2. Tool Execution: Uses Gmail Send, Tavily Search, and custom file processing tools
3. Clarification Handling: Manages OAuth authentication and user confirmations
4. Streaming Updates: Provides real-time progress via execution hooks

Processing Pipeline

1. Input Analysis: Parses lead information and uploaded files
2. Company Research: Uses Tavily API to research target organizations
3. Email Generation: Creates personalized emails using OpenAI's LLM
4. Authentication: Handles Gmail OAuth if not already authenticated
5. Email Sending: Delivers emails through Gmail API
6. Results: Returns execution summary and final outputs

Development

Backend Development

• Code Formatting: black . && isort .
• Linting: flake8
• Type Checking: mypy .
• Testing: pytest

Frontend Development

• Development Server: yarn start
• Build: yarn build
• Testing: yarn test

Troubleshooting

Common Issues

1. PortiaAI Authentication Errors:

   • Verify your PortiaAI API key is correct
   • Check you have access to PortiaAI Cloud features

2. Gmail Authentication Fails:

   • Ensure the OAuth redirect URL is properly configured
   • Check that the PortiaAI Gmail tool is available

3. File Processing Errors:

   • Verify file formats are supported (PDF, CSV, TXT)
   • Check file size limits

4. Real-time Updates Not Working:

   • Ensure CORS is properly configured
   • Check that SSE connections are not blocked

Logging

The backend provides detailed logging. Check the console output for:

• PortiaAI plan generation and execution
• File processing results
• Authentication flows
• Error details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License.