mailcop

README

mailcop

A Go package for validating email addresses according to RFC 5322 and additional rules. It uses the Go standard library for syntax validation and provides options for checking DNS records, disposable email domains, free email providers, and reserved domains.

Features

• RFC 5322 email syntax validation using the Go standard library
• Recognizes IANA reserved domains (example.com, .test TLD, etc.)
• Identifies disposable email domains (optional)
• Detects free email providers (optional)
• Optional DNS MX record validation (optional, requires network access)
• Concurrent validation for multiple addresses

Installation

go get github.com/patrickward/mailcop

Usage

Basic validation:

validator, err := mailcop.New(mailcop.DefaultOptions())
if err != nil {
    log.Fatal(err)
}

result := validator.Validate("user@example.com")
if !result.IsValid {
    log.Printf("Invalid email: %v", result.Error)
}

Custom validation options:

opts := mailcop.Options{
    CheckDNS:           true,
    CheckDisposable:    false,
    CheckFreeProvider:  false,
    DNSCacheTTL:        1 * time.Hour,
    DNSCacheSize:       1000,
    DNSTimeout:         3 * time.Second,
    DisposableListURL:  "https://disposable.github.io/disposable-email-domains/domains.json",
    FreeProvidersURL:   "",
    MaxEmailLength:     254,
    MinDomainLength:    1,
    RejectDisposable:   false,
    RejectFreeProvider: false,
    RejectIPDomains:    true,
	RejectNamedEmails:  true,
    RejectReserved:     true,
}

validator, err := mailcop.New(opts)
if err != nil {
    log.Fatal(err)
}

result := validator.Validate("user@example.com")
fmt.Printf("Name: %s, Address: %s, Valid: %v\n", result.Name, result.Address, result.IsValid)

Validate multiple addresses concurrently:

emails := []string{
    "user1@example.com",
    "user2@gmail.com",
    "invalid@",
}

results := validator.ValidateMany(emails)
for _, result := range results {
    fmt.Printf("Name: %s, Address: %s, Valid: %v\n", result.Name, result.Address, result.IsValid)
}

Validation Result

The ValidationResult struct provides detailed information about the validation:

type ValidationResult struct {
    Name           string        // Parsed name from email
    Address        string        // Normalized email address
    Original       string        // Original email address input
    IsValid        bool          // Whether the email is valid
    IsDisposable   bool          // Whether the domain is disposable
    IsFreeProvider bool          // Whether the domain is a free provider
    IsReserved     bool          // Whether the domain is reserved
    ValidationTime time.Duration // Time taken to validate
    Error          error         // Validation error
}

Free Email Providers

The CheckFreeProvider option can be used to detect free email providers. Disabled by default.

You can provide a list of free email domains by setting the FreeProvidersURL option to a URL that returns a JSON array of strings:

[
    "gmail.com",
    "yahoo.com",
    "hotmail.com"
]

You can add providers via the RegisterFreeProviders method:

    validator.RegisterFreeProviders([]string{"gmail.com", "yahoo.com"})

Disposable Email Domains

The CheckDisposable option can be used to detect disposable email domains. Disabled by default.

You can provide a list of disposable domains by setting the DisposableListURL option to a URL that returns a JSON array of strings:

[
    "mailinator.com",
    "guerrillamail.com",
    "10minutemail.com"
]

You can add domains via the RegisterDisposableDomains method:

    validator.RegisterDisposableDomains([]string{"mailinator.com", "guerrillamail.com"})

Documentation

Index

• func DefaultFreeProviders() map[string]struct{}
• type Options
  • func DefaultOptions() Options
• type ValidationResult
  • func (vr ValidationResult) ErrorMessage() string
• type Validator
  • func New(options Options) (*Validator, error)
  • func (v *Validator) LoadDisposableDomains(urlStr string) error
  • func (v *Validator) LoadFreeProviders(urlStr string) error
  • func (v *Validator) RegisterDisposableDomains(domains []string)
  • func (v *Validator) RegisterFreeProviders(providers []string)
  • func (v *Validator) Validate(email string) ValidationResult
  • func (v *Validator) ValidateMany(emails []string) []ValidationResult

Functions

func DefaultFreeProviders

func DefaultFreeProviders() map[string]struct{}

DefaultFreeProviders returns the default free email providers

Types

type Options

type Options struct {
	CheckDNS           bool          // Whether to perform DNS MX lookup
	CheckDisposable    bool          // Whether to check for disposable domains
	CheckFreeProvider  bool          // Whether to check for free email providers
	DNSCacheTTL        time.Duration // TTL for DNS cache
	DNSCacheSize       int           // Maximum number of DNS cache entries
	DNSTimeout         time.Duration // Timeout for DNS lookups
	DisposableListURL  string        // URL for disposable domains list
	FreeProvidersURL   string        // URL for free email providers list
	MaxEmailLength     int           // Maximum email length
	MinDomainLength    int           // Minimum domain length
	RejectDisposable   bool          // Whether to invalidate disposable domains
	RejectFreeProvider bool          // Whether to invalidate free email providers
	RejectIPDomains    bool          // Whether to reject IP address domains
	RejectNamedEmails  bool          // Whether to reject named email addresses (e.g. "First Last <first.last@example.com>")
	RejectReserved     bool          // Whether to invalidate reserved example domains
}

Options contains configuration options for email validation

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default validator options

type ValidationResult

type ValidationResult struct {
	Address        string        // Normalized email address
	IsDisposable   bool          // Whether the domain is disposable
	IsFreeProvider bool          // Whether the domain is a free provider
	IsIPDomain     bool          // Whether the domain is an IP address
	IsReserved     bool          // Whether the domain is reserved
	IsValid        bool          // Whether the email is valid
	LastError      error         // Validation error
	Name           string        // Parsed name from email
	Original       string        // Original email address input
	ValidationTime time.Duration // Time taken to validate
}

func (ValidationResult) ErrorMessage

func (vr ValidationResult) ErrorMessage() string

ErrorMessage returns the last validation error as a string if present, otherwise an empty string

type Validator

type Validator struct {
	// contains filtered or unexported fields
}

func New

func New(options Options) (*Validator, error)

func (*Validator) LoadDisposableDomains

func (v *Validator) LoadDisposableDomains(urlStr string) error

LoadDisposableDomains loads a list of disposable domains from a JSON file or URL

func (*Validator) LoadFreeProviders

func (v *Validator) LoadFreeProviders(urlStr string) error

LoadFreeProviders loads a list of free email providers from a JSON file or URL

func (*Validator) RegisterDisposableDomains

func (v *Validator) RegisterDisposableDomains(domains []string)

RegisterDisposableDomains manually adds domains to the disposable domains list

func (*Validator) RegisterFreeProviders

func (v *Validator) RegisterFreeProviders(providers []string)

RegisterFreeProviders manually adds domains to the free providers list

func (*Validator) Validate

func (v *Validator) Validate(email string) ValidationResult

Validate checks a single email address

func (*Validator) ValidateMany

func (v *Validator) ValidateMany(emails []string) []ValidationResult

ValidateMany validates multiple email addresses concurrently