README
¶
MailCheck
A professional, modular Go package for high-accuracy email and domain validation.
Features
- Common Provider Check: Instantly validates emails from popular services (Gmail, Outlook, etc.).
- Disposable Email Detection: Blocks temporary and disposable email domains using configurable lists.
- Blacklisted TLDs: Prevents registrations from TLDs commonly associated with spam (e.g.,
.tk,.ml). - Heuristic Analysis: Detects suspicious domains based on length, character patterns, and entropy.
- Fast Infrastructure Check: Verifies if a domain has an active web presence.
- Fully Configurable: Easily extend popular domains, blocked TLDs, and disposable lists.
Disclaimer: While
mailcheckuses comprehensive community lists and advanced heuristics, it cannot guarantee 100% detection of all temporary or disposable email addresses as and when they are created.
Installation
go get github.com/jigarvarma2k20/mailcheck
Usage
Basic Usage (Zero Config)
By default, mailcheck will try to fetch the latest disposable domain list from GitHub. If the network is unavailable, it will automatically fall back to a local domains.txt file.
package main
import (
"fmt"
"github.com/jigarvarma2k20/mailcheck"
)
func main() {
// Works out of the box with default GitHub list + fallback
v := mailcheck.New(mailcheck.Config{})
defer v.Stop()
if v.Validate("user@gmail.com") {
fmt.Println("Valid email!")
}
}
Advanced Configuration
v := mailcheck.New(mailcheck.Config{
DisposableFile: "path/to/disposable_domains.txt",
DisposableURLs: []string{
"https://raw.githubusercontent.com/TempMailDetector/Temporary-Email-Domain-Blocklist/refs/heads/main/domains.txt",
},
UpdateInterval: 24 * time.Hour, // Optional: defaults to 24h if URLs are set
PopularDomains: []string{"gmail.com", "yahoo.com", "outlook.com"},
BlockedTLDs: []string{"xyz", "top", "party"},
DialTimeout: 500 * time.Millisecond,
})
defer v.Stop()
Methods
Validate(email string) bool: Comprehensive validation check.IsPopularDomain(domain string) bool: Check if domain is a major provider.IsDisposableDomain(domain string) bool: Check against disposable list.IsBlockedTLD(domain string) bool: Check if TLD is blacklisted.HasWebsiteFast(domain string) bool: Quick TCP check for web presence.
Credits
Special thanks to TempMailDetector for providing the comprehensive disposable domain list used in this project.
License
MIT
Documentation
¶
Index ¶
Constants ¶
const (
DefaultDisposableURL = "https://raw.githubusercontent.com/TempMailDetector/Temporary-Email-Domain-Blocklist/refs/heads/main/domains.txt"
)
Variables ¶
var ( // DefaultPopularDomains is a list of common email providers. DefaultPopularDomains = []string{ "gmail.com", "googlemail.com", "yahoo.com", "yahoo.co.uk", "yahoo.co.in", "yahoo.co.jp", "yahoo.fr", "yahoo.de", "yahoo.it", "yahoo.es", "outlook.com", "hotmail.com", "live.com", "msn.com", "icloud.com", "me.com", "mac.com", "proton.me", "protonmail.com", "zoho.com", "zoho.eu", "zoho.in", "yandex.com", "yandex.ru", "mail.ru", "inbox.ru", "list.ru", "bk.ru", "mail.com", "gmx.com", "gmx.de", "aol.com", "fastmail.com", "fastmail.fm", "hushmail.com", "tutanota.com", "tuta.com", "qq.com", "163.com", "126.com", "naver.com", "daum.net", "rediffmail.com", } // DefaultBlockedTLDs contains TLDs often used for spam or disposable emails. DefaultBlockedTLDs = []string{ "gq", "cf", "ml", "tk", } )
Functions ¶
func GetParentDomain ¶
GetParentDomain extracts the root domain and TLD from a given domain string. Example: "sub.example.com" -> "example.com"
func SuspiciousDomain ¶
SuspiciousDomain performs heuristic analysis on a domain name to detect patterns commonly associated with spam or generated domains (e.g., excessive length, repeated consonants, or unusual digit/hyphen counts).
Types ¶
type Config ¶
type Config struct {
// DisposableFile is the path to a local text file containing disposable domains (one per line).
// If empty, and no DisposableURLs succeed, it defaults to "domains.txt".
DisposableFile string
// DisposableURLs is a list of URLs to remote text files containing disposable domains.
// Defaults to DefaultDisposableURL if empty.
DisposableURLs []string
// UpdateInterval is the period after which the URLs will be re-fetched automatically.
// If 0 and DisposableURLs are provided, it defaults to 24 hours.
UpdateInterval time.Duration
// PopularDomains is an optional list of domains to treat as trusted providers.
// If empty, the package's DefaultPopularDomains will be used.
PopularDomains []string
// BlockedTLDs is an optional list of top-level domains to block.
// If empty, the package's DefaultBlockedTLDs will be used.
BlockedTLDs []string
// DialTimeout is the timeout for the TCP connection check (HasWebsiteFast).
// If not set, a default of 450ms is used.
DialTimeout time.Duration
}
Config allows for customizing the Validator instance.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator provides methods for validating emails and domains.
func New ¶
New creates and initializes a new Validator using the provided configuration. It handles loading disposable domain lists from local files and remote URLs, and sets up the internal allow/block lists.
func (*Validator) HasWebsiteFast ¶
HasWebsiteFast checks if the domain has a server responding on port 443 (HTTPS). This is a heuristic to verify if the domain has an active web infrastructure.
func (*Validator) IsBlockedTLD ¶
IsBlockedTLD returns true if the domain's top-level domain is in the blocked list.
func (*Validator) IsDisposableDomain ¶
IsDisposableDomain returns true if the domain or any of its parent domains exist in the loaded disposable domain lists.
func (*Validator) IsPopularDomain ¶
IsPopularDomain returns true if the domain is a well-known email provider (e.g., gmail.com, outlook.com). This is often used to bypass stricter checks.
Source Files
Directories