English | 中文文档

An automated registration tool for Tavily accounts using intelligent email solutions, supporting batch registration, captcha recognition, and API key extraction.

This project is inspired by and built upon the foundation of yatotm/tavily-register. The original project provided excellent groundwork for Tavily automation, and this version expands upon it with:

• Enhanced Cloudflare Email Routing integration
• Improved captcha recognition system
• Complete localization and documentation
• Streamlined user experience

After obtaining Tavily API keys using this registration tool, we highly recommend deploying them with yatotm/tavily-mcp-loadbalancer for production use:

• Load Balancing: Distribute requests across multiple API keys
• High Availability: Automatic failover when keys reach limits
• Rate Limiting: Smart rotation to maximize API key usage
• Monitoring: Track usage and performance across all keys
• Easy Integration: Simple MCP-compatible interface

# Clone the load balancer project
git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git

# Configure your API keys from the api_keys.md file
# Follow the setup instructions in the project README

# Start the load balancer
npm start

This combination provides a complete solution from API key acquisition to production deployment.

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Tavily API    │───▶│  Custom Domain   │───▶│   Cloudflare    │
│  Registration   │    │  (your-domain.com) │    │  Email Routing  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                       │
                                                       ▼
                                            ┌─────────────────┐
                                            │   Tempmail      │
                                            │  (@mailto.plus) │
                                            └─────────────────┘
                                                       │
                                                       ▼
                                            ┌─────────────────┐
                                            │ Auto Registration│
                                            │     System      │
                                            └─────────────────┘

How it works:

1. System generates unique email: prefix{name}{timestamp}@your-domain.com
2. Tavily sends verification email to this address
3. Cloudflare Email Routing forwards all emails to your tempmail
4. Auto-registration system checks tempmail inbox
5. System extracts verification link and completes registration
6. API Key is automatically extracted and saved

Step 1: Get Custom Domain → Step 2: Configure Cloudflare → Step 3: Setup Tempmail → Step 4: Run Registration

Follow these steps in order:

1. Register a custom domain (e.g., from Namecheap, GoDaddy, etc.)
2. Configure Cloudflare DNS for your domain
3. Setup Cloudflare Email Routing (see detailed guide below)
4. Configure tempmail in config.py
5. Prepare names dataset (names-dataset.txt)
6. Run the registration system

• Python 3.8+
• Playwright
• MCP server (for captcha recognition)
• Custom domain with Cloudflare DNS
• Tempmail account

pip install playwright
pip install -r requirements.txt
playwright install

Edit the config.py file:

# Tempmail configuration
TEMP_MAIL_USERNAME = "your_username"  # replace with your tempmail username
TEMP_MAIL_EPIN = "your_epin"          # replace with your tempmail PIN code
TEMP_MAIL_EXT = "@mailto.plus"       # tempmail email extension

# Domain configuration (optional)
CUSTOM_DOMAIN = "your-domain.com"     # your custom domain, set to None if not available

To receive emails from Tavily at your custom domain, you need to configure Cloudflare Email Routing to forward emails to your tempmail address. This is crucial for the automated registration process.

• A custom domain (e.g., your-domain.com)
• Domain managed by Cloudflare DNS
• Tempmail account (already configured in config.py)

Step 1: Enable Email Routing

1. Log in to Cloudflare Dashboard
2. Select your account and domain
3. Go to Email > Email Routing
4. Click Enable Email Routing if not already enabled

Step 2: Configure DNS Records

1. In your Cloudflare dashboard, go to DNS > Records
2. Ensure you have the following MX records:

   Type: MX
   Name: @
   Mail server: mx.cloudflare.net
   Priority: 0
   TTL: Auto
   

3. Add additional MX records if needed:

   Type: MX
   Name: @
   Mail server: mx1.cloudflare.net
   Priority: 10
   TTL: Auto
   

Step 3: Set Up Email Forwarding Rules

1. Go to Email > Email Routing > Routes
2. Click Create address
3. In Custom address, enter your destination tempmail address:

   your-tempmail-username@mailto.plus
   

4. In Action dropdown, select Send to an email
5. In Destination, enter your tempmail address:

   your-tempmail-username@mailto.plus
   

6. Click Save

Step 4: Configure Catch-All Address (Recommended)

1. In Email Routing > Routes, enable Catch-all address
2. Set Action to Send to an email
3. Set Destination to your tempmail address
4. Click Save

This catch-all setup ensures that any email sent to any address at your domain (like random123@your-domain.com) will be forwarded to your tempmail inbox.

Step 5: Verify Destination Address

1. Cloudflare will send a verification email to your tempmail address
2. Check your tempmail inbox and click the verification link
3. The email rule will become active after verification

Send a test email to test@your-domain.com and verify it appears in your tempmail inbox. This should work within minutes of setup completion.

• Email routing typically takes 5-10 minutes to become fully active
• DNS propagation may take up to 24 hours in some cases
• All email rules are disabled until the destination address is verified
• Destination addresses are shared at the account level and can be reused with any domain

The project requires a names dataset to generate unique email addresses:

1. Download dataset file

   • Download CSV files from public name dataset websites
   • Recommended datasets contain English names, one name per line
   • Recommend downloading at least 10,000 names

2. Prepare dataset file

   # Convert downloaded data file to simple format, one name per line
   # Then rename to names-dataset.txt

3. Place dataset

   • Put names-dataset.txt file in project root directory
   • Ensure file encoding is UTF-8

python run_registration.py

# Batch register 3 accounts in headless mode
python run_registration.py --headless --count 3 --non-interactive

# Batch register 5 accounts in foreground mode
python run_registration.py --count 5 --non-interactive

After running, a menu will be displayed:

Tavily Auto Registration System
============================================================
Intelligent Email-based Automated Registration
ZAI Captcha Recognition | Names Dataset | Custom Domain
Domain Configuration: your-domain.com
============================================================

Select Operation:
1. Start Registration
2. View Configuration
3. Exit

Please select (1-3): 1

Browser Configuration:
1. Foreground Mode (observable process)
2. Background Mode (headless mode, faster)

Select browser mode (1/2): 1

Number of Accounts to Register (1-100): 5

python run_registration.py [options]

Options:
  --headless              Run in background mode
  --count COUNT           Number of accounts to register (1-100)
  --non-interactive       Non-interactive mode, use default settings

# Tempmail service configuration
TEMP_MAIL_USERNAME = "username"      # tempmail username
TEMP_MAIL_EPIN = "123456789"          # tempmail PIN code
TEMP_MAIL_EXT = "@mailto.plus"        # email extension
CUSTOM_DOMAIN = "domain.com"           # custom domain (optional)

# Registration configuration
DEFAULT_PASSWORD = "TavilyAuto123!"     # default password

# File paths
API_KEYS_FILE = "api_keys.md"           # API Key save file

# Browser configuration
HEADLESS = False                        # default foreground mode
BROWSER_TYPE = "firefox"               # browser type

• File name: names-dataset.txt
• Format: One name per line, UTF-8 encoding
• Content: English names (e.g., john, mary, david, etc.)
• Quantity: Recommend 10,000+ for uniqueness
• Location: Project root directory

• Browser fingerprint spoofing
• Human behavior simulation
• Random delays and mouse movements
• Proxy support

After successful registration, API keys will be saved in the api_keys.md file:

email,password,API Key,registration time
example123@domain.com,TavilyAuto123!,tvly-abcdef123456789,2024-01-01 12:00:00;

1. Names Dataset: Must prepare names-dataset.txt file, otherwise the program will error and exit
2. Captcha Limitations: Only recognizes text captchas, complex image captchas require manual handling
3. Rate Control: Reasonably control registration frequency to avoid being limited
4. Legal Use: Only for legal automated testing purposes

1. Names dataset not found

   Names dataset file not found: names-dataset.txt
   Please download the names dataset file and place it in the project root directory
   

   • Download names dataset file
   • Rename to names-dataset.txt
   • Place in project root directory

2. Tempmail configuration error

   • Check if TEMP_MAIL_USERNAME and TEMP_MAIL_EPIN are correct
   • Ensure network connection is normal

3. Captcha recognition failure

   • Check if MCP server is running normally
   • Confirm captcha is text format (not image selection)

4. Cloudflare email forwarding not working

   Email not received in tempmail inbox
   

   • Verify DNS MX records are properly configured
   • Check Email Routing rules are active (not disabled)
   • Ensure destination address is verified in Cloudflare
   • Wait at least 10 minutes for DNS propagation
   • Test with a simple email to verify forwarding works

5. Email routing delays

   Verification email received but delayed
   

   • Email routing can take 5-10 minutes to activate
   • Check DNS propagation status using tools like whatsmydns.net
   • Verify MX records are pointing to mx.cloudflare.net
   • Contact Cloudflare support if issues persist

6. Catch-all address not working

   Emails to random@domain.com not being forwarded
   

   • Ensure catch-all address is enabled in Email Routing settings
   • Check that catch-all rule is active (not disabled)
   • Verify destination address is properly set and verified

This project is for learning and legal testing purposes only. Users need to comply with the terms of service and laws of related services.

Issues and Pull Requests are welcome to improve this project.