USER_GUIDE.md

EmailCraft AI - Complete User Guide

Your Complete Guide to Generating High-Quality Cold Outreach Emails

Version 1.0 | Last Updated: 2024

🏠 Home | 🚀 Quick Start | 📧 Single Email | 🗺️ Lead Generation | 📦 Batch Processing | 📊 Analytics

---

Table of Contents

1. Getting Started
2. Single Email Generation
3. Lead Generation
4. Batch Processing
5. Analytics Dashboard
6. Email History
7. Custom Templates
8. Portfolio Management
9. Tips & Best Practices
10. Troubleshooting

---

Getting Started

Accessing the Application

1. Open your browser and navigate to the application URL
2. You'll see the landing page with an overview of features

Screenshot: EmailCraft AI Landing Page with hero, features, and workflows

3. Click "Launch App" to access the main application

Understanding the Interface

The application has 5 main tabs:

Tab	Icon	Purpose
New Email	✉️	Generate a single personalized email
Lead Generation	🗺️	Find leads and generate emails automatically
Batch Emails	📦	Process multiple emails from CSV
History	🕐	View all previously generated emails
Analytics	📊	Track performance and insights

Screenshot: Main application interface showing all 5 tabs

Theme Toggle

Switch between Light and Dark mode using the theme toggle button in the top-right corner.

Screenshot: Light mode (left) vs Dark mode (right) comparison

---

Single Email Generation

Generate a personalized cold email for a specific job posting or role.

Input & Customization

You have two input options and can customize sender details:

Screenshot: Complete email generation form with all input fields

Option A: Job URL (Recommended)

1. Find a job posting on LinkedIn, Indeed, or any job board
2. Copy the URL
3. Paste it into the "Job URL" field
4. The system will automatically scrape:
   • Job title and role
   • Required skills
   • Company information
   • Job description

Supported platforms:

• LinkedIn Jobs
• Indeed
• Glassdoor
• Company career pages

Option B: Manual Input

If you don't have a job URL:

1. Enter the Role (e.g., "Senior DevOps Engineer")
2. Enter the Industry (e.g., "FinTech, SaaS")
3. Optionally add Company Name and Recipient Name

Sender Information

• Your Name: How you want to sign the email
• Your Company: Your company or "Freelance"
• Your Services: What you offer (e.g., "AI development services")

Tone Selection

• Professional: Formal, business-appropriate
• Casual: Friendly, conversational
• Enthusiastic: Energetic, passionate

Generate & Review

1. Click "Generate Email" button
2. Wait 20-30 seconds while the AI:
   • Scrapes job details (if URL provided)
   • Analyzes recipient persona
   • Retrieves relevant templates
   • Matches portfolio items
   • Generates personalized email
   • Evaluates and optimizes

Screenshot: Generated email with quality metrics and actions

The result includes:

1. Quality Score (0-10)

• Overall email quality rating
• Higher is better (aim for 7+)

2. Email Content

• Subject Line: Attention-grabbing opener
• Body: Personalized message
• CTA: Clear call-to-action

3. Quality Metrics

• Clarity (0-10): Easy to understand?
• Tone (0-10): Appropriate tone?
• Length (0-10): Right length?
• Personalization (0-10): Tailored to recipient?
• Spam Safe (0-10): Avoids spam triggers?

4. Feedback

• Strengths: What works well
• Issues: Areas to improve

5. Alternative Subject Lines

• 3 additional subject line options
• Click to replace the current one

6. Portfolio Items

• Relevant projects automatically included
• Matched to job requirements

7. Actions

• Copy: Copy to clipboard
• Download .eml: Save as email file
• Regenerate: Create a new version

---

Lead Generation

Automatically find businesses and generate personalized emails at scale.

What is Lead Generation?

Instead of targeting specific job postings, Lead Generation:

1. Scrapes businesses from Google Maps
2. Generates personalized emails for each lead
3. Exports everything to Excel

Define Search & Configure Outreach

Screenshot: Lead generation form with search criteria and sender info

Required Fields:

1. Business Type

   • What type of businesses to find
   • Examples: "software companies", "restaurants", "law firms", "real estate agencies", "marketing agencies"

2. Location

   • City, state, or region
   • Examples: "San Francisco, CA", "New York", "Austin, Texas", "Los Angeles"

3. Number of Leads

   • How many businesses to find (5-50)
   • Start with 10-20 for testing

Sender Information:

• Your Name: How you'll sign emails
• Your Company: Your business name
• Your Services: What you offer to these businesses

Generate & Review Results

1. Click "Generate Leads & Emails"
2. Wait while the system processes (~30 seconds per lead)
3. Review the results table

Screenshot: Lead results table with company info, scores, and actions

Results Table Shows:

Column	Description
#	Lead number
Company Info	Name, website, email, contact
Subject	Email subject line (truncated)
Score	Quality score (0-10)
Metrics	C/T/L/P/S scores
Status	Success or Failed
Actions	View, Copy buttons

Success Card:

• Total leads found
• Successful emails generated
• Summary statistics

View Individual Emails:

• Click "View Email" (👁️ icon) to see full details
• Includes lead information, full email content, quality metrics, and portfolio items

Processing Time:

• ~30 seconds per lead
• 10 leads = ~5 minutes
• 20 leads = ~10 minutes

Export Results

Click "Download Results (Excel)" to export all data:

Screenshot: Excel export showing all lead data

Excel file includes all lead data:

• Lead information (company, website, phone, address, category, rating, reviews)
• Email content (subject, body, CTA)
• Quality scores and metrics (overall score + 5 individual metrics)
• AI feedback (strengths, issues, alternative subjects, portfolio items)

Use cases:

• Import to CRM
• Add contact emails manually or use email finder tools
• Send via email marketing tool
• Manual review and editing
• Track outreach campaigns

Note: Email addresses are not automatically found. You'll need to add them manually or use external email finder services.

---

Batch Processing

Process multiple emails at once from a CSV file.

When to Use Batch Processing

• You have a list of job URLs or companies
• Need to generate 10-200+ emails
• Want to process overnight
• Exporting to CRM or email tool

Prepare & Upload CSV

Download Template:

1. Click "Download Template" button
2. Open the CSV file

Template columns:

Column	Required	Description	Example
job_url	Yes*	Job posting URL	https://linkedin.com/jobs/...
role	Yes*	Job title	Senior DevOps Engineer
industry	No	Industry/sector	FinTech, SaaS
company_name	No	Company name	Stripe
recipient_name	No	Contact name	John Smith

*Either job_url OR role is required

Fill Your Data:

Option 1 - Job URLs:

job_url,role,industry,company_name,recipient_name
https://linkedin.com/jobs/123,,,Stripe,
https://indeed.com/job/456,,,Airbnb,

Option 2 - Manual Roles:

job_url,role,industry,company_name,recipient_name
,Senior DevOps Engineer,FinTech,Stripe,John Smith
,Product Manager,SaaS,Notion,Sarah Johnson

Upload & Configure:

Screenshot: CSV upload area with drag-drop and file preview

Two ways to upload:

1. Drag & Drop: Drag CSV file onto the upload zone
2. Click to Browse: Click and select file

File requirements:

• Format: .csv
• Size: Up to 10MB
• Rows: 10-200 recommended

Configure Settings:

1. Sender Information (Your Name, Company, Services)
2. Tone (Professional recommended for batch)
3. Rate Limiting (Automatic, ~30 seconds per email)

Process & Review Results

1. Click "Start Batch Processing"
2. Monitor progress in real-time
3. Review results when complete

Screenshot: Batch processing results with progress and summary

Progress shows:

• Current email being processed
• Percentage complete
• Estimated time remaining
• Success/failure count
• Live log of each email

Summary Statistics:

• Total emails processed
• Successful generations
• Failed attempts
• Average quality score

Results Table:

• All emails with scores
• Status indicators
• Quick actions (view, copy)

Error Handling:

• Failed emails shown separately
• Error messages for debugging
• Can retry failed items

Export Options:

1. Download Excel - All emails in spreadsheet with metrics
2. Download CSV - Plain text format compatible with all tools

---

Analytics Dashboard

Track performance, trends, and insights across all your email generation activities.

Screenshot: Complete analytics dashboard with stats, charts, and activity

Overview Statistics

Key Metrics Cards:

1. Total Emails Generated

   • All-time count
   • Growth trend

2. Average Quality Score

   • Mean score across all emails
   • Target: 7.5+

3. Success Rate

   • Percentage of successful generations
   • Should be 95%+

4. Total Leads Sourced

   • From lead generation feature
   • Unique businesses found

Performance Analytics

Performance by Role:

• Most common roles targeted
• Average score per role
• Number of emails per role
• Use to identify best-performing roles and optimize targeting

Score Distribution:

• Histogram showing email count in each score range
• Distribution pattern analysis
• Quality consistency tracking
• Ideal: Most emails in 7-9 range, few below 6

Template Performance:

• Which templates are used most
• Average score per template
• Template effectiveness comparison
• Use to identify best templates and remove underperforming ones

Activity & Trends

Recent Activity Timeline:

• Latest emails generated
• Scores and timestamps
• Quick access to view details

Trends Over Time:

• Line chart showing score trends by day/week
• Improvement tracking over time
• Seasonal patterns identification
• Use to measure optimization impact

---

Email History

Access and manage all previously generated emails.

Screenshot: Email history page with search, filters, and email list

Viewing & Managing History

History shows:

• All emails ever generated
• Sorted by date (newest first)
• Quick preview of each email

Search & Filter

Search by:

• Company name
• Role/position
• Keywords in email

Filter by:

• Date range
• Quality score
• Status (success/failed)
• Source (single/batch/lead gen)

Email Details & Actions

Click any email to view:

• Original input parameters
• Generated email content
• Quality metrics
• Timestamp
• Source (which feature used)

For each email:

• View: See full details
• Copy: Copy to clipboard
• Regenerate: Create new version
• Delete: Remove from history

Export History

Export options:

• All history to Excel
• Filtered results only
• Date range selection

---

Custom Templates

Add your own email templates to improve personalization.

Why Use Custom Templates?

• Industry-specific: Create templates for your niche
• Brand voice: Match your communication style
• Proven patterns: Use what works for you
• Better results: More relevant templates = better emails

Adding Templates

See the complete guide: Custom Templates Guide

Quick Steps:

1. Open template file: data/email_templates.json

2. Add your template:

   {
     "id": "my_template_1",
     "title": "My Custom Template",
     "industry": "Technology",
     "use_case": "Product demo",
     "subject_line": "Subject with {placeholders}",
     "body": "Email body...",
     "cta": "Book a call",
     "performance_score": 8.0
   }

3. Restart application

Template Placeholders

Available placeholders:

Placeholder	Replaced With
{name}	Recipient name
{company}	Company name
{role}	Job role
{industry}	Industry
{product}	Your product/service
{your_name}	Sender name

Template Performance

View how your templates perform in the Analytics dashboard under "Template Performance" section.

---

Portfolio Management

Manage your portfolio items for automatic inclusion in emails.

What is Portfolio Matching?

The system automatically:

1. Analyzes job requirements
2. Searches your portfolio
3. Includes relevant projects in emails

Adding Portfolio Items

Edit portfolio file: data/portfolio.json

Or use CSV: data/my_portfolio.csv

Portfolio Structure

{
  "title": "E-commerce Platform",
  "description": "Built scalable platform handling 1M+ users",
  "tech_stack": "React, Node.js, PostgreSQL, AWS",
  "link": "https://github.com/username/project",
  "category": "Web Development"
}

How Matching Works

Example:

Job requires: React, Node.js, AWS

Your portfolio:

• ✅ "E-commerce Platform" (React, Node.js, AWS) - Matched!
• ❌ "Mobile App" (Flutter, Firebase) - Not matched
• ✅ "API Service" (Node.js, AWS) - Matched!

Result: Top 2 matched projects included in email

---

Tips & Best Practices

For Single Emails

✅ DO:

• Use job URLs when possible (more accurate)
• Fill in company and recipient name
• Review and customize before sending
• Test different tones

❌ DON'T:

• Use generic roles without context
• Skip sender information
• Send without reviewing
• Ignore quality scores below 7

For Lead Generation

✅ DO:

• Start with 10-20 leads to test
• Use specific business types
• Include location for better targeting
• Review a few emails before bulk sending

❌ DON'T:

• Generate 50+ leads without testing
• Use vague business types
• Send without reviewing samples

For Batch Processing

✅ DO:

• Validate CSV before uploading
• Include as much data as possible
• Process during off-hours
• Export and review before sending

❌ DON'T:

• Upload without previewing
• Process 200+ without testing
• Ignore failed emails
• Send directly without review

Quality Score Guidelines

Score	Quality	Action
9-10	Excellent	Send as-is
7-8.9	Good	Minor tweaks
5-6.9	Fair	Review and edit
Below 5	Poor	Regenerate

Personalization Tips

High personalization:

• Mention specific company achievements
• Reference job requirements
• Include relevant portfolio items
• Use recipient's name

Low personalization:

• Generic templates
• No company research
• Missing context
• Copy-paste approach

---

Troubleshooting

Common Issues

1. "Failed to scrape job URL"

Causes:

• Invalid URL
• Job posting removed
• Website blocking scraper

Solutions:

• ✅ Verify URL is correct
• ✅ Try manual input instead
• ✅ Use a different job posting

2. "No templates found"

Causes:

• Template file missing
• Vector database not initialized

Solutions:

• ✅ Check data/email_templates.json exists
• ✅ Restart application
• ✅ Check logs for errors

3. "Portfolio items not matching"

Causes:

• Tech stack mismatch
• Incorrect keywords
• Portfolio file format error

Solutions:

• ✅ Use exact technology names
• ✅ Add more keywords to tech_stack
• ✅ Validate JSON format

4. "Lead generation finds no businesses"

Causes:

• Too specific search criteria
• Location has no results
• API key issues

Solutions:

• ✅ Broaden business type
• ✅ Try different location
• ✅ Check Apify API key

5. "Batch processing stuck"

Causes:

• API rate limits
• Network issues
• Invalid CSV data

Solutions:

• ✅ Wait for rate limit reset
• ✅ Check internet connection
• ✅ Validate CSV format

6. "Low quality scores"

Causes:

• Insufficient input data
• Poor template match
• Generic content

Solutions:

• ✅ Provide more details
• ✅ Add custom templates
• ✅ Include company/recipient info

Getting Help

Check logs:

# View application logs
tail -f logs/app.log

Common log messages:

Message	Meaning
✅ Email generated	Success
❌ Error generating	Failed
⚠️ Rate limit	Too many requests
📚 Retrieved templates	Templates found

Need more help?

• Check README.md for setup
• Review CUSTOM_TEMPLATES_GUIDE.md
• Check LEAD_SOURCING_GUIDE.md

---

Keyboard Shortcuts

Shortcut	Action
Ctrl/Cmd + K	Focus search
Ctrl/Cmd + N	New email tab
Ctrl/Cmd + B	Batch tab
Ctrl/Cmd + H	History tab
Ctrl/Cmd + A	Analytics tab
Ctrl/Cmd + T	Toggle theme

---

FAQ

How long does it take to generate an email?

Single email: 20-30 seconds Lead generation: ~30 seconds per lead Batch processing: ~30 seconds per email

Can I edit emails after generation?

Yes! Copy the email and edit in your email client or text editor.

How many emails can I generate?

No hard limit, but recommended:

• Single: Unlimited
• Lead Gen: 50 per batch
• Batch: 200 per file

Are emails saved automatically?

Yes! All emails are saved in the History tab.

Can I use this for other languages?

Currently English only. Multi-language support coming soon.

Is my data secure?

Yes! All data is:

• Stored locally in SQLite
• Not shared with third parties
• Encrypted in transit

Can I integrate with my CRM?

Export to Excel/CSV and import to any CRM. Direct integrations coming soon.

---

What's Next?

Recommended Workflow

1. Start with Single Email - Learn the system
2. Try Lead Generation - Test automated prospecting
3. Add Custom Templates - Improve personalization
4. Use Batch Processing - Scale your outreach
5. Monitor Analytics - Track and optimize

Advanced Features (Coming Soon)

• 🎨 Visual template editor
• 🔗 CRM integrations
• 📧 Email sending directly from app
• 🤖 A/B testing
• 📱 Mobile app
• 🌍 Multi-language support

---

Support

Need help? We're here for you!

• 📧 Email: support@emailcraft-ai.com
• 💬 Discord: Join our community
• 📖 Docs: Full documentation
• 🐛 Issues: GitHub Issues

---

Made with ❤️ by the EmailCraft AI Team

⬆ Back to Top