CrewAI Job Search & Email Outreach

---

Table of Contents

1. Project Overview
2. Features
3. Quickstart Guide
4. Installation
5. Environment Setup
6. Project Setup for Contributors
7. Creating a New CrewAI Project from Scratch
8. Commands Reference
   • Job Search
   • HR and Company Research
   • Email Finder
   • Personalized Email Generation
   • Email Sending
9. Project Structure
10. How the Code Works
11. How to Extend or Modify
12. Troubleshooting
13. Support & Resources

---

Project Overview

Welcome to the CrewAI Job Search & Email Outreach project! This project helps you search for jobs across multiple platforms (LinkedIn, Indeed, Glassdoor, etc.), find HR contacts, research companies, discover professional emails, and send personalized outreach emails. It supports both direct (scripted) and agent (LLM-powered) modes.

---

Features

• Job Search: Search for job listings across multiple platforms simultaneously
• Customizable: Easily configure search parameters like role, location, and more
• CSV Export: Results are saved in a structured CSV format for easy analysis
• HR Contact Finding: Find HR contacts at companies from your job listings using Apollo.io
• Company Research: Retrieve detailed company information for better interview preparation
• Anymail Finder Integration: Find and verify professional emails (by LinkedIn, name, company, bulk, etc.)
• Personalized Email Generation: Generate customized outreach emails using your resume and job data
• Email Sending: Send personalized emails with automatic formatting fixes

---

Quickstart Guide

Prerequisites

• Python: Version >=3.10, <3.13
• uv: For fast dependency management (uv documentation)

Installation

1. Install uv (if not already installed):

   pip install uv

2. Install project dependencies:

   uv pip install -r requirements.txt

Environment Setup

Create a .env file in the project root and add your API keys as needed:

OPENAI_API_KEY=your-openai-key      # For agent mode and email generation
APOLLO_API_KEY=your-apollo-key      # For HR/company info (optional)
ANYMAIL_API_KEY=your-anymail-key    # For Anymail Finder features

# Email sending configuration (if using email features)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
EMAIL_ADDRESS=your_email@gmail.com
EMAIL_PASSWORD=your_app_password_here

---

Project Setup for Contributors

If you've cloned this repository, follow these steps to get started:

1. Ensure you have Python 3.10-3.12 installed:

   python --version

2. Install uv (if not already installed):

   pip install uv

3. Install project dependencies:

   uv pip install -r requirements.txt

   Alternatively, using pyproject.toml:

   uv pip install .

4. Configure environment variables: Create a .env file in the project root with your API keys:

   OPENAI_API_KEY=your-openai-key      # Required for agent mode and email generation
   APOLLO_API_KEY=your-apollo-key      # Optional for HR/company features
   ANYMAIL_API_KEY=your-anymail-key    # Optional for email search features
   
   # Email configuration
   SMTP_SERVER=smtp.gmail.com
   SMTP_PORT=587
   EMAIL_ADDRESS=your_email@gmail.com
   EMAIL_PASSWORD=your_app_password_here
   

5. Run the application:

   uv run src/crew_ai/main.py

   Or for a specific job search:

   uv run src/crew_ai/main.py --role "Software Engineer" --location "San Francisco" --results 30

---

Creating a New CrewAI Project from Scratch

If you want to start your own CrewAI project (with agents, tasks, and tools) from scratch, you can use the CrewAI CLI to scaffold the entire project structure for you.

1. Install CrewAI CLI

If you haven't already, install the CrewAI CLI globally:

pip install crewai

2. Scaffold a New Project

Run the following command, replacing <project_name> with your desired project name:

crewai create crew <project_name>
cd <project_name>

This will generate a project with the following structure:

<project_name>/
├── .gitignore
├── pyproject.toml
├── README.md
├── .env
└── src/
    └── <project_name>/
        ├── __init__.py
        ├── main.py
        ├── crew.py
        ├── tools/
        │   ├── custom_tool.py
        │   └── __init__.py
        └── config/
            ├── agents.yaml
            └── tasks.yaml

3. Customize Your Project

After creating the scaffold, you'll need to:

1. Edit Configuration Files: Modify agents.yaml and tasks.yaml in the config/ directory to define your agents and their tasks.
2. Set Up Environment: Create a .env file with your API keys (OpenAI, etc.).
3. Install Dependencies: Run crewai install to install required dependencies.
4. Run Your Crew: Execute crewai run to start your crew.

4. Understanding Key Components

• agents.yaml: Define your AI agents, their roles, goals, and backstories
• tasks.yaml: Set up tasks for agents to perform with descriptions and expected outputs
• crew.py: Define how agents collaborate and the workflow between them
• tools/: Add custom tools for agents to use for specific tasks

For more details, see the CrewAI Documentation.

---

Commands Reference

Job Search

Basic Job Search (Direct Mode)

uv run src/crew_ai/main.py

Custom Job Search

uv run src/crew_ai/main.py --role "Data Scientist" --location "Remote" --results 50 --hours 48

Agent Mode (LLM-powered)

uv run src/crew_ai/main.py --agent

HR and Company Research

Find HR Contacts (Apollo.io API)

uv run src/crew_ai/main.py --hr-contacts --input jobs.csv

Find Company Information (Apollo.io API)

uv run src/crew_ai/main.py --org-info --input jobs.csv

Email Finder

Find Email by LinkedIn URL

uv run src/crew_ai/main.py --find-email-by-linkedin "https://linkedin.com/in/john-doe"

Find Person Email by Name and Domain/Company

uv run src/crew_ai/main.py --find-person-email --name "John Doe" --domain "microsoft.com"
# OR
uv run src/crew_ai/main.py --find-person-email --name "John Doe" --company "Microsoft"

Find Decision Maker Email

uv run src/crew_ai/main.py --find-decision-maker-email --domain "microsoft.com" --category "HR"

Find All Emails at a Company

uv run src/crew_ai/main.py --find-all-emails-at-company --domain "microsoft.com"

Bulk Email Search

uv run src/crew_ai/main.py --bulk-email-search --input-csv leads.csv --search-type person --output-csv results.csv

Get Bulk Search Info

uv run src/crew_ai/main.py --get-bulk-search-info <searchId>

Verify Email Address

uv run src/crew_ai/main.py --verify-email "john.doe@microsoft.com"

Personalized Email Generation

Generate personalized outreach emails using job/HR contact data and your resume:

uv run src/crew_ai/main.py --generate-personalized-emails \
  --input-csv hr_contacts.csv \
  --output-csv outreach.csv \
  --resume your_resume.pdf

Optional parameters:

• --user-profile profile.txt: Additional user profile information
• --limit 5: Generate only a specific number of emails

The email generation process automatically handles:

• Clean subject line formatting
• Proper link formatting for LinkedIn and GitHub
• No duplicate subject lines in email bodies
• Professional plain text formatting

Email Sending

Send the generated personalized emails:

# Test mode (no actual emails sent)
uv run src/crew_ai/main.py --send-emails --input-csv outreach.csv --test-mode

# Live mode (sends actual emails)
uv run src/crew_ai/main.py --send-emails --input-csv outreach.csv

You can also use agent mode for email sending:

uv run src/crew_ai/main.py --send-emails --input-csv outreach.csv --test-mode --agent

---

Project Structure

crew_ai/
├── src/crew_ai/
│   ├── main.py            # Main entry point, CLI logic
│   ├── crew.py            # Crew/agent/task orchestration
│   ├── tools/             # Custom tools (job search, LinkedIn, email, etc.)
│   │   ├── email_sender_tool.py   # Email sending functionality
│   │   ├── personalized_email_agent.py # Email generation with AI
│   │   └── ...
│   ├── config/
│   │   ├── agents.yaml    # Agent definitions
│   │   └── tasks.yaml     # Task definitions
│   └── ...
├── csv/                   # Output CSVs (jobs, HR contacts, emails)
├── knowledge/user_preference.txt # User preferences (role, location)
├── .env                   # API keys and environment variables
├── requirements.txt/pyproject.toml # Dependencies
└── README.md              # Documentation

---

How the Code Works

• main.py — Handles CLI, parses arguments, and runs the appropriate workflow
• crew.py — Defines the CrewAI agent/task structure and orchestrates agent-based workflows
• tools/ — Implements custom tools for job search, LinkedIn/Apollo integration, email generation/sending
• config/agents.yaml and tasks.yaml — Define agent roles, goals, and tasks for CrewAI

Email Generation Process

The personalized email generation uses an LLM to:

1. Parse your resume and job details
2. Craft a professional, personalized outreach email
3. Automatically format the email properly with correct links
4. Save to CSV for sending

Email Sending Process

The email sender tool:

1. Reads the CSV with personalized emails
2. Connects to your SMTP server using credentials from .env
3. Sends emails to recipients or simulates sending in test mode
4. Provides a report on success/failures

---

How to Extend or Modify

• Agents/Tasks: Edit YAML files in src/crew_ai/config/
• Custom Tools: Add or modify Python files in src/crew_ai/tools/
• User Preferences: Edit knowledge/user_preference.txt
• API Integrations: Add keys to .env and update tool logic as needed
• Email Templates: Modify personalized_email_agent.py to change prompts and formatting

---

Troubleshooting

• Missing API Key: Make sure your .env file is set up correctly
• No Results: Try adjusting your search parameters or check your internet connection
• Email Sending Failures: Check SMTP settings and ensure you have proper app passwords if using Gmail
• Errors: Check logs/output for error messages; ensure dependencies are installed

---

Support & Resources

• CrewAI Documentation
• Anymail Finder API Docs
• GitHub Issues
• Discord Community

---

Happy job hunting and automating! 🚀