# Integrate Tomba Finder with LiteCart

## Overview

The **LiteCart Disposable Email Blocker** is an essential security add-on designed specifically for LiteCart e-commerce platforms. This tool provides a superior line of defense against fake registrations and spam accounts by validating email addresses in real-time during customer registration and account creation.

### Why Choose This Add-on?

- 🛡️ **E-commerce Security**: Protects your store from fake customer accounts
- 📧 **Email Quality Assurance**: Ensures legitimate customer email addresses
- 🚫 **Spam Prevention**: Dramatically reduces spam registrations and fake orders
- ⚡ **Real-time Validation**: Instant feedback during registration process
- **Enhanced User Experience**: Clear guidance for valid email requirements
- 📊 **Customer Data Integrity**: Maintains clean and reliable customer database

### Key Benefits for E-commerce

- **Fraud Prevention**: Reduces fake accounts that can lead to fraudulent orders
- **Marketing Effectiveness**: Ensures email marketing reaches real customers
- **Customer Support Efficiency**: Reduces support tickets from unreachable customers
- **Payment Security**: Valid emails improve payment verification processes
- **Analytics Accuracy**: Clean customer data provides better business insights
- **Compliance Support**: Helps meet email verification requirements

## Features

### Core Protection Features

- **Invalid Email Detection**: Identifies malformed email addresses
- **Invalid Domain Verification**: Blocks emails from non-existent domains
- **Disposable Email Blocking**: Prevents temporary/throwaway email services
- **Webmail Control**: Configurable blocking or warnings for free webmail providers
- **Real-time Validation**: Instant feedback during customer registration
- **Custom Error Messages**: Personalized validation messages for your brand

### 🔄 Advanced E-commerce Features

- **Daily Domain Updates**: Automatically updated disposable email database
- **Customer Journey Protection**: Validates emails at all registration points
- **Order Validation**: Ensures order confirmation emails reach customers
- **Newsletter Signup Protection**: Prevents spam in email marketing lists
- **Account Recovery Support**: Ensures password reset emails are deliverable
- **Multi-language Support**: Customizable messages for international stores

### 📋 Validation Coverage

| Validation Type         | Description                        | E-commerce Impact               |
| ----------------------- | ---------------------------------- | ------------------------------- |
| **Email Format**        | Syntax validation (RFC compliance) | Prevents basic input errors     |
| **Domain Existence**    | DNS lookup verification            | Ensures deliverable addresses   |
| **Disposable Services** | Temporary email detection          | Blocks fake accounts            |
| **Webmail Services**    | Free provider identification       | Configurable business policy    |
| **Spam Domains**        | Known abuse domain blocking        | Reduces malicious registrations |

### 🏪 LiteCart Integration

- **vMod Technology**: Built using LiteCart's native vMod system
- **Admin Panel Integration**: Easy configuration through LiteCart admin
- **Theme Compatibility**: Works with all LiteCart themes
- **Performance Optimized**: Minimal impact on store performance
- **Mobile Responsive**: Full mobile device support
- **Multi-store Support**: Compatible with multiple store configurations

## Installation

### Prerequisites

- **LiteCart Version**: 2.5.0 or higher (vMod support required)
- **PHP Version**: 7.2 or higher
- **JavaScript**: Enabled in customer browsers
- **Admin Access**: LiteCart administrator privileges
- **Web Server**: Apache/Nginx with proper .htaccess support

### Step 1: Download the Add-on

1. **Download** the latest release from [GitHub](https://github.com/tomba-io/litecart-disposable-email-blocker)
2. **Extract** the downloaded ZIP file to your computer
3. **Locate** the `public_html` folder in the extracted files

### Step 2: Upload Files

#### Method A: FTP/SFTP Upload

```bash
# Connect to your LiteCart server
sftp username@your-server.com

# Navigate to your LiteCart installation
cd /path/to/litecart/

# Upload the files
put -r local/public_html/* public_html/
```

#### Method B: Control Panel File Manager

1. **Access** your hosting control panel (cPanel, DirectAdmin, etc.)
2. **Open** File Manager
3. **Navigate** to your LiteCart installation directory
4. **Upload** and extract the ZIP file
5. **Move** contents from `public_html` folder to your LiteCart root

#### Method C: Direct Server Access

```bash
# Navigate to LiteCart installation
cd /path/to/litecart/

# Copy uploaded files
cp -r /tmp/disposable-email-blocker/public_html/* .

# Set proper permissions
chmod 644 vmods/disposable_email_blocker.xml
```

### Step 3: Install via vMod Manager

1. **Log in** to your LiteCart Admin Panel
2. **Navigate** to `Modules` → `vMods`
3. **Locate** "Disposable Email Blocker" in the available vMods list
4. **Click** the checkbox next to the add-on
5. **Click** "Enable" button to activate
6. **Confirm** the add-on appears in the enabled list

### Step 4: Verify Installation

Check that the following files are properly installed:

```
public_html/
├── vmods/
│   └── disposable_email_blocker.xml ✓
```

## Configuration

### Access Add-on Settings

1. **Navigate** to LiteCart Admin Panel
2. **Go to** `Settings` → `Email` or find in the right sidebar
3. **Locate** "Disposable Email Blocker" settings section
4. **Configure** options according to your store needs

### Core Settings

#### General Configuration

| Setting             | Description                     | Default   | Recommended           |
| ------------------- | ------------------------------- | --------- | --------------------- |
| **Enable Add-on**   | Master on/off switch            | Enabled   | Enabled               |
| **Validation Mode** | When to validate emails         | Real-time | Real-time             |
| **Show Debug Info** | Display debug information       | Disabled  | Disabled (production) |
| **Cache Duration**  | API response cache time (hours) | 24        | 24                    |

## Usage

### For Store Administrators

#### Basic Setup Process

1. **Install and activate** the add-on via vMod manager
2. **Configure settings** in the admin panel
3. **Test customer registration** with various email types
4. **Monitor customer feedback** and adjust settings as needed
5. **Review validation logs** for effectiveness

### Customer Experience

#### Valid Registration Flow

```
Customer enters: john.doe@company.com
Validation: Email format valid
Domain check: Domain exists and valid
Service check: Not disposable/spam
Result: Registration proceeds smoothly
```

#### Disposable Email Detection

```
Customer enters: temp123@10minutemail.com
❌ Validation: Disposable service detected
❌ Result: Error message displayed
Message: "Disposable email addresses are not allowed"
Action: Customer guided to use permanent email
```

#### Webmail Handling (Configurable)

```
Customer enters: customer@gmail.com
⚠️ Validation: Webmail provider detected
📋 Policy: Warn (configurable to allow/warn/block)
Message: "Consider using a business email"
Result: Registration allowed with warning
```

### Integration Points

The add-on validates emails at these key points:

- **Customer Registration**: New account creation
- **Guest Checkout**: Order placement without account
- **Newsletter Signup**: Marketing list subscription
- **Contact Forms**: Customer service inquiries
- **Account Updates**: Email address changes
- **B2B Registration**: Business account creation

## Troubleshooting

### Common Issues

#### Issue: Add-on Not Appearing in vMod Manager

**Symptoms:**

- vMod not listed in available modifications
- XML file present but not detected

**Solutions:**

1. **Check XML syntax**: Validate vMod XML structure
    ```bash
    xmllint --noout vmods/disposable_email_blocker.xml
    ```
2. **Verify file permissions**: Ensure web server can read the file
    ```bash
    chmod 644 vmods/disposable_email_blocker.xml
    ```
3. **Clear vMod cache**: Delete cache files
    ```bash
    rm -rf storage/vmods/cache/*
    ```
4. **Check LiteCart version**: Ensure vMod support is available

#### Issue: JavaScript Validation Not Working

**Symptoms:**

- No real-time validation occurring
- Disposable emails passing through
- Browser console errors

**Solutions:**

1. **Verify JavaScript file loading**:
    ```
    Check: http://yourstore.com/js/disposable-email-blocker.min.js
    ```
2. **Check browser console** for JavaScript errors
3. **Ensure jQuery compatibility** (LiteCart uses jQuery)
4. **Test with different browsers** and devices

#### Issue: False Positives (Valid Emails Blocked)

**Symptoms:**

- Legitimate business emails rejected
- Customers unable to register
- Specific domains incorrectly flagged

**Solutions:**

1. **Add to whitelist**: Configure allowed domains in settings
2. **Adjust webmail policy**: Change from "block" to "warn"
3. **Update domain database**: Ensure latest disposable domain list
4. **Review custom blocked domains**: Remove incorrectly added domains

#### Issue: Performance Impact

**Symptoms:**

- Slow page loading on registration forms
- Increased server response times
- Customer complaints about site speed

**Solutions:**

1. **Enable caching**: Increase cache duration for API responses
2. **Optimize API timeout**: Reduce timeout to 3-5 seconds
3. **Use CDN**: Load JavaScript files from CDN
4. **Monitor server resources**: Check CPU and memory usage

### Debug Mode

Enable debug mode for troubleshooting:

1. **Edit vMod settings** to enable debug mode
2. **Open browser developer console**
3. **Attempt customer registration** with test emails
4. **Review detailed console output**

Debug output example:

```javascript
LiteCart Disposable Email Blocker Debug:
- Store Mode: retail
- Email: test@10minutemail.com
- Domain: 10minutemail.com
- API Response: {"disposable": true, "webmail": false}
- Policy: block_disposable = true
- Action: BLOCKED
- Message: Disposable email addresses are not allowed
```

### Log File Analysis

Check LiteCart error logs:

```bash
# Common log locations
tail -f storage/logs/errors.log
tail -f /var/log/apache2/error.log
tail -f /var/log/nginx/error.log

# Look for entries containing "disposable" or "email blocker"
grep -i "disposable\|email.*block" storage/logs/errors.log
```

## Support

### Documentation & Resources

- 📚 **Add-on Documentation**: [GitHub Wiki](https://github.com/tomba-io/litecart-disposable-email-blocker/wiki)
- 🏪 **LiteCart Official**: [LiteCart Add-ons](https://litecart.net/en/addons)
- 🔧 **vMod Development**: [LiteCart vMod Guide](https://litecart.net/wiki/how_to_create_a_vmod)
- 🌐 **Tomba.io API**: [Developer Documentation](https://docs.tomba.io/)

### Support Channels

- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/tomba-io/litecart-disposable-email-blocker/issues)
- 💬 **Feature Requests**: [GitHub Discussions](https://github.com/tomba-io/litecart-disposable-email-blocker/discussions)
- 📧 **Direct Support**: [support@tomba.io](mailto:support@tomba.io)
- 🏛️ **LiteCart Community**: [LiteCart Forums](https://litecart.net/forums)

### Frequently Asked Questions

#### Q: Is this add-on free to use?

**A:** Yes, the Disposable Email Blocker add-on is completely free for all LiteCart stores.

#### Q: Does it work with custom LiteCart themes?

**A:** Yes, the add-on is designed to work with all LiteCart themes using the vMod system.

#### Q: Can I customize the validation messages?

**A:** Absolutely! All messages are fully customizable through the LiteCart admin panel settings.

#### Q: Will this impact my store's performance?

**A:** The add-on uses client-side JavaScript validation with minimal server impact. API calls are cached to reduce overhead.

#### Q: Can I whitelist specific domains?

**A:** Yes, you can configure custom allowed domains and exceptions in the admin settings.

#### Q: Does it validate emails on guest checkout?

**A:** Yes, the add-on validates emails at all registration points including guest checkout, configurable per your needs.