📧 Yopmail API

Automated Yopmail inbox scraping microservice with stealth browser automation

Quick Start • API Docs • Configuration • Examples

---

✨ Features

🎯 Core Capabilities 🔍 Inbox Scraping — Headless Chromium with stealth anti-detection 🔐 OTP Extraction — Auto-detect 4-8 digit verification codes 🔗 Link Extraction — Extract URLs and href from email HTML 🎫 Token Detection — Find hex, base64, and query parameter tokens

🚀 Performance & Security ⚡ Concurrency — Puppeteer Cluster for parallel requests 🛡️ Rate Limiting — 15 req/min with API key bypass 🤖 CAPTCHA Detection — Auto-detect with screenshot capture 🐳 Docker Ready — Multi-stage build with VPN support

---

📋 Table of Contents

• Quick Start
• Configuration
• API Reference
• Examples
• Docker & VPN
• Project Structure
• Development
• Disclaimer
• License

---

🚀 Quick Start

Local Development

# Clone repository
git clone https://github.com/your-username/yopmail-api.git
cd yopmail-api

# Install dependencies
npm install

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Start development server (with auto-reload)
npm run dev

Docker Deployment

# Setup environment
cp .env.example .env

# Build and start containers
docker compose up --build -d

# Check logs
docker compose logs -f yopmail-api

API will be available at: http://localhost:3000

---

⚙️ Configuration

Copy .env.example to .env and configure:

Core Settings

Variable	Default	Description
PORT	3000	Server port
MAX_BROWSERS	2	Max concurrent browser pages
BYPASS_API_KEYS	(empty)	Comma-separated API keys for rate limit bypass

VPN Settings (Optional)

Variable	Default	Description
VPN_SERVICE_PROVIDER	surfshark	VPN provider
VPN_TYPE	wireguard	VPN protocol
WIREGUARD_PRIVATE_KEY	(required)	Your WireGuard private key
WIREGUARD_ADDRESSES	10.14.0.2/16	WireGuard IP addresses
SERVER_COUNTRIES	Singapore,Japan,US	VPN server countries

Rate Limit Bypass

Send the x-internal-api-key header to bypass rate limiting:

curl -H "x-internal-api-key: your-secret-key" \
  "http://localhost:3000/api/yopmail?email=test"

---

📡 API

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2026-07-17T14:00:00.000Z",
  "message": "Cluster is running"
}

---

Fetch Inbox

GET /api/yopmail?email=<prefix>

Parameters:

Name	Type	Required	Description
email	string	✅ Yes	Email prefix (without @yopmail.com)

Success Response:

{
  "status": "success",
  "email": "testuser@yopmail.com",
  "data": {
    "subject": "Your verification code",
    "sender": "noreply@example.com"
  },
  "latest_email": {
    "subject": "Your verification code",
    "body_text": "Your verification code is: 123456",
    "body_html": "<p>Your verification code is: <strong>123456</strong></p>"
  },
  "links_found": [
    "https://example.com/verify?token=abc123"
  ],
  "tokens_found": [
    "abc123def456"
  ],
  "otp_data": {
    "codes_found": ["123456"],
    "primary_code": "123456",
    "total_codes": 1
  },
  "metadata": {
    "total_emails": 3,
    "processing_time_ms": 2150,
    "timestamp": "2026-07-17T14:00:00.000Z"
  }
}

Error Response:

{
  "status": "error",
  "message": "Failed to extract email.",
  "errorDetail": "Timeout waiting for selector"
}

---

💡 Examples

cURL

# Health check
curl http://localhost:3000/health

# Fetch inbox
curl "http://localhost:3000/api/yopmail?email=testuser123"

JavaScript (Node.js)

const axios = require('axios');

async function getYopmail(emailPrefix) {
  try {
    const response = await axios.get('http://localhost:3000/api/yopmail', {
      params: { email: emailPrefix }
    });

    const data = response.data;
    console.log('Email:', data.email);
    console.log('Subject:', data.latest_email?.subject);
    
    if (data.otp_data?.codes_found?.length > 0) {
      console.log('OTP:', data.otp_data.primary_code);
    }

    return data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

getYopmail('mytest123');

Python

import requests

def get_yopmail(email_prefix):
    try:
        response = requests.get(
            'http://localhost:3000/api/yopmail',
            params={'email': email_prefix}
        )
        data = response.json()

        print(f"Email: {data['email']}")
        print(f"Subject: {data.get('latest_email', {}).get('subject')}")

        otp_data = data.get('otp_data', {})
        if otp_data.get('codes_found'):
            print(f"OTP: {otp_data['primary_code']}")

        return data
    except Exception as e:
        print(f"Error: {e}")

get_yopmail('mytest123')

📖 More examples: See API_EXAMPLES.md for PowerShell and advanced usage.

---

🐳 Docker & VPN

The docker-compose.yml includes Gluetun for VPN routing via WireGuard.

Without VPN

Remove the gluetun service and network_mode from yopmail-api if you don't need VPN:

services:
  yopmail-api:
    build: .
    ports:
      - "3000:3000"
    # Remove: network_mode: "service:gluetun"

With VPN

Configure VPN credentials in .env:

VPN_SERVICE_PROVIDER=surfshark
VPN_TYPE=wireguard
WIREGUARD_PRIVATE_KEY=your-private-key
WIREGUARD_ADDRESSES=10.14.0.2/16
SERVER_COUNTRIES=Singapore,Japan,United States

---

📁 Project Structure

yopmail-api/
├── server.js              # Main application (Express + Puppeteer Cluster)
├── Dockerfile             # Container image definition
├── docker-compose.yml     # Orchestration with VPN support
├── .env.example           # Environment variable template
├── package.json           # Dependencies and scripts
├── API_EXAMPLES.md        # Client usage examples
├── screenshots/           # Debug screenshots (gitignored)
└── .github/workflows/     # CI/CD pipeline

---

🛠️ Development

Available Scripts

Command	Description
npm start	Start production server
npm run dev	Start with auto-reload (nodemon)
npm run docker:build	Build Docker image
npm run docker:run	Run Docker container

Requirements

• Node.js >= 18.0.0
• Docker & Docker Compose (for containerized deployment)

---

⚠️ Disclaimer

For legitimate testing and development purposes only.

This project is intended for automated testing pipelines, CI/CD email verification, and development environment testing. Use responsibly and in compliance with the terms of service of any services you interact with.

The authors are not responsible for any misuse of this software.

---

📄 License

This project is licensed under the MIT License.

---

⬆ Back to Top

Made with ❤️ for developers and testers