📧 Email Finder API

Find anyone's email address using their name and domain via SMTP verification

---

⚡ Quick Start

curl "http://YOUR_SERVER/email-api.php?name=John+Doe&domain=example.com"

Response:

{
  "status": "ok",
  "email": "john.doe@example.com",
  "confidence": 100,
  "verification_status": "verified"
}

---

✨ Features

Feature	Description
🔍 Smart Pattern Matching	60-180+ email patterns tested automatically
⚡ Batch SMTP Verification	2x faster with batch processing
✅ Triple Verification	3 checks for 100% confidence
💾 Smart Caching	Instant response for repeated queries
🛑 Early Exit	Stops immediately when valid email found
🇮🇳 Indian Name Support	Handles 2-5 word names perfectly

---

📖 How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  1. Cache   │────▶│  2. Catch-All │────▶│  3. Name Parse  │
│   Check     │     │   Detection   │     │                 │
└─────────────┘     └──────────────┘     └─────────────────┘
                                                  │
                                                  ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  6. Return  │◀────│  5. Triple   │◀────│  4. Batch SMTP  │
│   & Cache   │     │   Verify     │     │   Verification  │
└─────────────┘     └──────────────┘     └─────────────────┘

---

🚀 API Reference

Parameters

Parameter	Required	Description
name	✅ Yes	Full name of the person
domain	✅ Yes	Email domain (e.g., example.com)
verbose	❌ No	Set to 1 for detailed response
skip_cache	❌ No	Set to 1 to force fresh search
timeout	❌ No	SMTP timeout in seconds (default: 12)

Response Codes

Status	Confidence	Meaning
verified	100%	Email confirmed (3/3 checks passed)
verified	85%	Likely valid (2/3 checks passed)
risky	70%	Rate limited but likely exists
risky	40%	Catch-all domain detected
not_found	-	No valid email found

---

📦 Installation

Requirements

• PHP 7.4+
• Apache/Nginx
• Port 25 outbound open

Setup

# 1. Clone the repository
git clone https://github.com/souravkr529/eMail-Finder.git

# 2. Navigate to directory
cd eMail-Finder

# 3. Create cache file
echo "{}" > email_cache.json

# 4. Create log directories
mkdir -p logs/{failed,timeout,error,ratelimit}

# 5. Set permissions
chmod 666 email_cache.json
chmod -R 777 logs/

---

📝 Examples

Basic Search

curl "http://server/email-api.php?name=John+Doe&domain=example.com"

Skip Cache (Fresh Search)

curl "http://server/email-api.php?name=John+Doe&domain=example.com&skip_cache=1"

Verbose Output

curl "http://server/email-api.php?name=John+Doe&domain=example.com&verbose=1"

POST Request

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"John Doe","domain":"example.com"}' \
  http://server/email-api.php

---

📊 Email Patterns

2-Word Names (60+ patterns)

first.last    → john.smith
flast         → jsmith
f.last        → j.smith
firstlast     → johnsmith
lfirst        → sjohn     (common in India)
first         → john
last          → smith

3-Word Names (90+ patterns)

first.mid.last  → john.michael.smith
fmid            → nmichael
mid             → michael
midlast         → michaelsmith

---

🔧 Configuration

Edit email-api.php:

$CFG = [
    'from_domain'    => 'verify.example.com',
    'max_retries'    => 2,
    'jitter_ms'      => [100, 300],
    'logs_enabled'   => true,
];

---

📁 File Structure

eMail-Finder/
├── email-api.php          # Main API file
├── email_cache.json       # Cache storage
├── README.md              # Documentation
└── logs/
    ├── failed/            # No email found
    ├── timeout/           # Processing > 3 min
    ├── error/             # PHP errors
    └── ratelimit/         # 450 rate limits

---

⚠️ Rate Limiting

If you see 450 errors:

1. Restart Server - Get new IP
2. Wait - Greylisting clears in few hours
3. IP Rotation - Use AWS Lambda for automatic rotation

---

📈 Performance

Metric	Value
Batch Size	2 emails/connection
Speed Improvement	2-3x faster
Triple Verify Time	~3 seconds
Cache Response	Instant

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⭐ Star History

If you find this project useful, please consider giving it a ⭐!

---

Made with ❤️ by Sourav Kumar