README

Mail server discovery on autopilot

PHP library for automatic detection of IMAP and SMTP server settings for any domain.

Installation

Option 1: Composer

composer require accountdesk/mail-autodetect

Option 2: Manual

Copy src/AutoDetector.php into your project and include it:

require_once 'path/to/AutoDetector.php';

Requirements:

• PHP >= 8.1
• ext-curl
• ext-simplexml

Usage

use MailAutodetect\AutoDetector;

$detector = new AutoDetector();

// With email address (recommended - enables Microsoft Autodiscover)
$result = $detector->autoDetect('user@example.com');

// With domain only (without Autodiscover)
$result = $detector->autoDetect('gmail.com');

print_r($result);

Output:

[
    'imap' => [
        [
            'host' => 'imap.gmail.com',
            'port' => 993,
            'ssl' => 'ssl',
            'auth' => 'OAuth2',
            'source' => 'mozilla_ispdb',
            'score' => 95,
            'sources' => ['mozilla_ispdb'],
            'match_count' => 1,
        ],
        // more candidates...
    ],
    'smtp' => [
        [
            'host' => 'smtp.gmail.com',
            'port' => 465,
            'ssl' => 'ssl',
            'auth' => 'OAuth2',
            'source' => 'mozilla_ispdb',
            'score' => 95,
            'sources' => ['mozilla_ispdb'],
            'match_count' => 1,
        ],
        // more candidates...
    ],
]

Configuration

$detector = new AutoDetector([
    'timeout_http' => 10,  // HTTP requests (default: 10s)
    'timeout_tcp'  => 3,   // TCP connections (default: 3s)
    'logger'       => $logger,  // PSR-3 logger (optional)
]);

// Threshold: stop early when IMAP+SMTP with score > threshold found
$result = $detector->autoDetect('example.com', threshold: 90);

Logging (PSR-3)

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

$logger = new Logger('mail-autodetect');
$logger->pushHandler(new StreamHandler('php://stderr', Logger::DEBUG));

$detector = new AutoDetector(['logger' => $logger]);

Log levels:

• info: Start/end of detection, threshold reached
• debug: Individual strategies, DNS/HTTP requests, cache hits
• warning: HTTP/DNS errors

Caching

DNS and HTTP results are automatically cached (in-memory per request). Multiple queries for the same domain won't trigger duplicate requests.

Detection Strategies

The library uses multiple strategies in descending reliability:

Score calculation:

• Servers found by multiple sources get +5 bonus per additional source
• Reverse DNS mismatch on guessed hosts: -15 points
• Maximum: 100 points

Response Format

Each candidate contains:

Security Considerations

Important: This library detects mail server configurations but does NOT validate them.

Before using detected settings with real credentials:

1. Always confirm with the user - Show the detected hostname/port and ask for explicit confirmation
2. Don't auto-connect - Never automatically test connections with real passwords
3. Validate the domain - Ensure the detected hosts belong to the expected domain

Example secure implementation:

$result = $detector->autoDetect($email);
$imap = $result['imap'][0] ?? null;

if ($imap) {
    // Show user the detected settings and ask for confirmation
    echo "Detected IMAP server: {$imap['host']}:{$imap['port']}\n";
    echo "Is this correct? (y/n): ";

    if (readline() !== 'y') {
        // Let user enter settings manually
    }
}

Why this matters: A malicious domain could configure autoconfig/autodiscover to point to an attacker-controlled server, potentially capturing credentials.

License

MIT

Testing

This library uses static analysis (Mago) instead of unit tests. Network-dependent libraries like this are better validated through real-world usage than mocked tests.