{"id":31654810,"url":"https://github.com/longcipher/mailguard-rs","last_synced_at":"2026-01-20T17:31:58.827Z","repository":{"id":315698906,"uuid":"1028735860","full_name":"longcipher/mailguard-rs","owner":"longcipher","description":"A Rust library to detect temporary and disposable email addresses","archived":false,"fork":false,"pushed_at":"2025-07-30T02:50:15.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-20T06:54:27.210Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longcipher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-30T01:48:19.000Z","updated_at":"2025-07-30T11:30:16.000Z","dependencies_parsed_at":"2025-09-20T07:04:31.250Z","dependency_job_id":null,"html_url":"https://github.com/longcipher/mailguard-rs","commit_stats":null,"previous_names":["longcipher/mailguard-rs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/longcipher/mailguard-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fmailguard-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fmailguard-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fmailguard-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fmailguard-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longcipher","download_url":"https://codeload.github.com/longcipher/mailguard-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fmailguard-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278773014,"owners_count":26043295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-07T12:17:04.717Z","updated_at":"2025-10-07T12:17:07.049Z","avatar_url":"https://github.com/longcipher.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MailGuard-RS\n\n🛡️ A fast temporary email and malicious domain detection library using SURBL DNS queries\n\n[中文文档](README.zh.md)\n\n## Features\n\n- ⚡ **Fast Detection**: Quick temporary email detection via SURBL DNS queries\n- 🔍 **Threat Classification**: Identify different threat types (spam, phishing, malware, etc.) based on DNS responses\n- 🚀 **Async Support**: Tokio-based asynchronous DNS queries\n- 💾 **Smart Caching**: Built-in cache mechanism to avoid duplicate queries\n- 📦 **Batch Processing**: Support for batch detection of multiple emails or domains\n- 🎯 **Type Safety**: Full Rust type system support\n\n## How It Works\n\nThis library detects temporary emails and malicious domains by querying DNS A records for `domain.tempmail.so.multi.surbl.org`. If the query returns an IP address in the `127.0.0.x` range, it indicates the domain is blacklisted.\n\n### Threat Type Classification\n\nThreat types are determined by the last octet of the returned IP address:\n\n| Last Octet | Threat Type | Severity | Description |\n|------------|-------------|----------|-------------|\n| 2, 9       | Spam        | 2        | Spam source |\n| 3          | Phishing    | 4        | Phishing website |\n| 4, 6, 7, 11| Malware     | 5        | Malware |\n| 5          | Botnet      | 4        | Botnet |\n| 10         | PUP         | 1        | Potentially Unwanted Program |\n\n## Quick Start\n\nAdd the following to your `Cargo.toml`:\n\n```toml\n[dependencies]\nmailguard-rs = \"0.1.0\"\ntokio = { version = \"1.0\", features = [\"full\"] }\n```\n\n### Features\n\nThis library supports optional features:\n\n- `cache` - Enable LRU caching functionality (disabled by default)\n\nTo enable caching:\n\n```toml\n[dependencies]\nmailguard-rs = { version = \"0.1.0\", features = [\"cache\"] }\ntokio = { version = \"1.0\", features = [\"full\"] }\n```\n\n### Basic Usage\n\n```rust\nuse mailguard_rs::check_email;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Check a single email\n    let status = check_email(\"test@10minutemail.com\").await?;\n    \n    if status.is_threat {\n        println!(\"⚠️  Detected temporary email: {}\", status.email);\n        if let Some(threat_type) = \u0026status.threat_type {\n            println!(\"Threat type: {} (Level: {})\", \n                threat_type.description(), \n                threat_type.severity_level()\n            );\n        }\n    } else {\n        println!(\"✅ Email is safe: {}\", status.email);\n    }\n    \n    Ok(())\n}\n```\n\n### Advanced Usage\n\n```rust\nuse mailguard_rs::{MailGuard, MailGuardConfig};\nuse std::time::Duration;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    // Create detector with custom configuration\n    let config = MailGuardConfig {\n        dns_timeout: Duration::from_secs(3),\n        enable_cache: true,\n        cache_ttl: Duration::from_secs(600), // 10 minutes cache\n    };\n    \n    let detector = MailGuard::with_config(config);\n    \n    // Batch detection\n    let emails = vec![\n        \"user1@gmail.com\",\n        \"user2@10minutemail.com\",\n        \"user3@guerrillamail.com\",\n    ];\n    \n    let results = detector.check_emails_batch(\u0026emails).await;\n    \n    for (email, result) in emails.iter().zip(results.iter()) {\n        match result {\n            Ok(status) =\u003e {\n                let cache_indicator = if status.from_cache { \" [cached]\" } else { \"\" };\n                println!(\"{}: {} {}\", \n                    email,\n                    if status.is_threat { \"⚠️ Temporary\" } else { \"✅ Safe\" },\n                    cache_indicator\n                );\n            }\n            Err(e) =\u003e {\n                println!(\"{}: ❌ Error: {}\", email, e);\n            }\n        }\n    }\n    \n    // Show cache statistics\n    if let Some(cache_size) = detector.cache_stats() {\n        println!(\"Cache entries: {}\", cache_size);\n    }\n    \n    Ok(())\n}\n```\n\n### Domain-Only Detection\n\n```rust\nuse mailguard_rs::check_domain;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let status = check_domain(\"mailinator.com\").await?;\n    \n    if status.is_threat {\n        println!(\"⚠️  Malicious domain: {}\", status.domain);\n    } else {\n        println!(\"✅ Domain is safe: {}\", status.domain);\n    }\n    \n    Ok(())\n}\n```\n\n## API Documentation\n\n### Structs\n\n#### `EmailStatus`\n```rust\npub struct EmailStatus {\n    pub email: String,              // Email address\n    pub domain: String,             // Domain name\n    pub is_threat: bool,            // Whether it's a threat\n    pub threat_type: Option\u003cThreatType\u003e, // Threat type if any\n    pub from_cache: bool,           // Whether result is from cache\n}\n```\n\n#### `DomainStatus`\n```rust\npub struct DomainStatus {\n    pub domain: String,             // Domain name\n    pub is_threat: bool,            // Whether it's a threat\n    pub threat_type: Option\u003cThreatType\u003e, // Threat type if any\n    pub from_cache: bool,           // Whether result is from cache\n}\n```\n\n#### `ThreatType`\n```rust\npub enum ThreatType {\n    Spam,                           // Spam source\n    Phishing,                       // Phishing website\n    Malware,                        // Malware\n    Botnet,                         // Botnet\n    Pup,                           // Potentially Unwanted Program\n    Unknown(u8),                   // Unknown threat type\n}\n```\n\n### Main Functions\n\n- `check_email(email: \u0026str) -\u003e Result\u003cEmailStatus, MailGuardError\u003e`\n- `check_domain(domain: \u0026str) -\u003e Result\u003cDomainStatus, MailGuardError\u003e`\n- `check_emails_batch(emails: \u0026[\u0026str]) -\u003e Vec\u003cResult\u003cEmailStatus, MailGuardError\u003e\u003e`\n\n## Running Examples\n\n```bash\n# Clone the repository\ngit clone https://github.com/longcipher/mailguard-rs.git\ncd mailguard-rs\n\n# Run the main example\ncargo run\n\n# Run simple example\ncargo run --example simple_usage\n\n# Run advanced example\ncargo run --example advanced_usage\n\n# Run tests\ncargo test\n```\n\n## Performance Characteristics\n\n- **DNS Queries**: Default timeout of 5 seconds\n- **Caching**: Default TTL of 5 minutes\n- **Memory Usage**: Low memory footprint with LRU cache strategy\n- **Concurrency**: Supports high-concurrency async queries\n\n## Error Handling\n\n```rust\nuse mailguard_rs::{check_email, MailGuardError};\n\nmatch check_email(\"invalid-email\").await {\n    Ok(status) =\u003e println!(\"Detection result: {:?}\", status),\n    Err(MailGuardError::InvalidEmail(email)) =\u003e {\n        println!(\"Invalid email format: {}\", email);\n    }\n    Err(MailGuardError::DnsError(e)) =\u003e {\n        println!(\"DNS query failed: {}\", e);\n    }\n    Err(e) =\u003e {\n        println!(\"Other error: {}\", e);\n    }\n}\n```\n\n## Configuration\n\n### `MailGuardConfig`\n```rust\npub struct MailGuardConfig {\n    pub dns_timeout: Duration,      // DNS query timeout (default: 5s)\n    pub enable_cache: bool,         // Enable caching (default: true)\n    pub cache_ttl: Duration,        // Cache TTL (default: 5 minutes)\n}\n```\n\n## Dependencies\n\n- `tokio` - Async runtime\n- `trust-dns-resolver` - DNS queries\n- `regex` - Email validation\n- `thiserror` - Error handling\n- `serde` - Serialization support\n- `lru` - Cache implementation\n- `tracing` - Structured logging support\n\n## License\n\nApache-2.0 License\n\n## Contributing\n\nIssues and Pull Requests are welcome!\n\n## Related Projects\n\n- [SURBL](https://www.surbl.org/) - URI DNS Blacklist Service\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history.\n\n## Support\n\nIf you find this project helpful, please consider giving it a ⭐ on GitHub!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fmailguard-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongcipher%2Fmailguard-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fmailguard-rs/lists"}