emailverifier

package module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2022 License: MIT Imports: 20 Imported by: 1

README

email-verifier

✉️ A Go library for email verification without sending any emails.

Build Status Godoc Coverage Status Go Report Card license

Features

  • Email Address Validation: validates if a string contains a valid email.
  • Email Verification Lookup via SMTP: performs an email verification on the passed email
  • MX Validation: checks the DNS MX records for the given domain name
  • Misc Validation: including Free email provider check, Role account validation, Disposable emails address (DEA) validation
  • Email Reachability: checks how confident in sending an email to the address

Install

Use go get to install this package.

go get -u github.com/AfterShip/email-verifier

Usage

Basic usage

Use Verify method to verify an email address with different dimensions

package main

import (
	"fmt"
	
	emailverifier "github.com/AfterShip/email-verifier"
)

var (
	verifier = emailverifier.NewVerifier()
)


func main() {
	email := "example@exampledomain.org"

	ret, err := verifier.Verify(email)
	if err != nil {
		fmt.Println("verify email address failed, error is: ", err)
		return
	}
	if !ret.Syntax.Valid {
		fmt.Println("email address syntax is invalid")
		return
	}

	fmt.Println("email validation result", ret)
	/*
		result is:
		{
			"email":"example@exampledomain.org",
			"disposable":false,
			"reachable":"unknown",
			"role_account":false,
			"free":false,
			"syntax":{
			"username":"example",
				"domain":"exampledomain.org",
				"valid":true
			},
			"has_mx_records":true,
			"smtp":null,
			"gravatar":null
		}
	*/
}
Email verification Lookup

Use CheckSMTP to performs an email verification lookup via SMTP.

var (
    verifier = emailverifier.
        NewVerifier().
        EnableSMTPCheck()
)

func main() {

    domain := "domain.org"
    username := "username"
    ret, err := verifier.CheckSMTP(domain, username)
    if err != nil {
        fmt.Println("check smtp failed: ", err)
        return
    }

    fmt.Println("smtp validation result: ", ret)

}

Note: because most of the ISPs block outgoing SMTP requests through port 25 to prevent email spamming, the module will not perform SMTP checking by default. You can initialize the verifier with EnableSMTPCheck() to enable such capability if port 25 is usable, or use a socks proxy to connect over SMTP

Use a SOCKS5 proxy to verify email

Support setting a SOCKS5 proxy to verify the email, proxyURI should be in the format: socks5://user:password@127.0.0.1:1080?timeout=5s

The protocol could be socks5, socks4 and socks4a.

var (
    verifier = emailverifier.
        NewVerifier().
        EnableSMTPCheck().
    	Proxy("socks5://user:password@127.0.0.1:1080?timeout=5s")
)

func main() {

    domain := "domain.org"
    username := "username"
    ret, err := verifier.CheckSMTP(domain, username)
    if err != nil {
        fmt.Println("check smtp failed: ", err)
        return
    }

    fmt.Println("smtp validation result: ", ret)

}
Misc Validation

To check if an email domain is disposable via IsDisposable

var (
    verifier = emailverifier.
        NewVerifier().
        EnableAutoUpdateDisposable()
)

func main() {
    domain := "domain.org"
    if verifier.IsDisposable(domain) {
        fmt.Printf("%s is a disposable domain\n", domain)
        return
    }
    fmt.Printf("%s is not a disposable domain\n", domain)
}

Note: It is possible to automatically update the disposable domains daily by initializing verifier with EnableAutoUpdateDisposable()

Suggestions for domain typo

Will check for typos in an email domain in addition to evaluating its validity. If we detect a possible typo, you will find a non-empty "suggestion" field in the validation result containing what we believe to be the correct domain. Also, you can use the SuggestDomain() method alone to check the domain for possible misspellings

func main() {
    domain := "gmai.com"
    suggestion := verifier.SuggestDomain(domain) 
    // suggestion should be `gmail.com`
    if suggestion != "" {
        fmt.Printf("domain %s is misspelled, right domain is %s. \n", domain, suggestion)
        return 
    }
    fmt.Printf("domain %s has no possible misspellings. \n", domain)
}

Note: When using the Verify() method, domain typo checking is not enabled by default, you can enable it in a verifier with EnableDomainSuggest()

For more detailed documentation, please check on godoc.org 👉 email-verifier

API

We provide a simple self-hosted API server script for reference.

The API interface is very simple. All you need to do is to send a GET request with the following URL.

The email parameter would be the target email you want to verify.

https://{your_host}/v1/{email}/verification

Similar Libraries Comparison

email-verifier trumail check-if-email-exists freemail
Features 〰️ 〰️ 〰️ 〰️
Disposable email address validation ✅ ✅, but not available in free lib ✅ ✅
Disposable address autoupdate ✅ 🤔 ❌ ❌
Free email provider check ✅ ✅, but not available in free lib ❌ ✅
Role account validation ✅ ❌ ✅ ❌
Syntax validation ✅ ✅ ✅ ❌
Email reachability ✅ ✅ ✅ ❌
DNS records validation ✅ ✅ ✅ ❌
Email deliverability ✅ ✅ ✅ ❌
Mailbox disabled ✅ ✅ ✅ ❌
Full inbox ✅ ✅ ✅ ❌
Host exists ✅ ✅ ✅ ❌
Catch-all ✅ ✅ ✅ ❌
Gravatar ✅ ✅, but not available in free lib ❌ ❌
Typo check ✅ ✅, but not available in free lib ❌ ❌
Use proxy to connect over SMTP ✅ ❌ ✅ ❌
Honeyport dection 🔜 ❌ ❌ ❌
Bounce email check 🔜 ❌ ❌ ❌
Tech 〰️ 〰️ 〰️ 〰️
Provide API ✅ ✅ ✅ ❌
Free API ✅ ❌ ❌ ❌
Language Go Go Rust JavaScript
Active maintain ✅ ❌ ✅ ✅
High Performance ✅ ❌ ✅ ✅

FAQ

The library hangs/takes a long time after 30 seconds when performing email verification lookup via SMTP

Most ISPs block outgoing SMTP requests through port 25 to prevent email spamming. email-verifier needs to have this port open to make a connection to the email's SMTP server. With the port being blocked, it is not possible to perform such checking, and it will instead hang until timeout error. Unfortunately, there is no easy workaround for this issue.

For more information, you may also visit this StackOverflow thread.

The output shows "connection refused" in the smtp.error field.

This error can also be due to SMTP ports being blocked by the ISP, see the above answer.

What does reachable: "unknown" means

This means that the server does not allow real-time verification of an email right now, or the email provider is a catch-all email server.

Credits

Contributing

For details on contributing to this repository, see the contributing guide.

License

This package is licensed under MIT license. See LICENSE for details.

Documentation

Index

Constants

View Source 
const (
	// Standard Errors
	ErrTimeout           = "The connection to the mail server has timed out"
	ErrNoSuchHost        = "Mail server does not exist"
	ErrServerUnavailable = "Mail server is unavailable"
	ErrBlocked           = "Blocked by mail server"

	// RCPT Errors
	ErrTryAgainLater           = "Try again later"
	ErrFullInbox               = "Recipient out of disk space"
	ErrTooManyRCPT             = "Too many recipients"
	ErrNoRelay                 = "Not an open relay"
	ErrMailboxBusy             = "Mailbox busy"
	ErrExceededMessagingLimits = "Messaging limits have been exceeded"
	ErrNotAllowed              = "Not Allowed"
	ErrNeedMAILBeforeRCPT      = "Need MAIL before RCPT"
	ErrRCPTHasMoved            = "Recipient has moved"
)

Variables

This section is empty.

Functions

func GenerateRandomEmail 

func GenerateRandomEmail(domain string) string

GenerateRandomEmail generates a random email address using the domain passed. Used primarily for checking the existence of a catch-all address

func IsAddressValid 

func IsAddressValid(email string) bool

IsAddressValid checks if email address is formatted correctly by using regex

Types

type Gravatar 

type Gravatar struct {
	HasGravatar bool   // whether has gravatar
	GravatarUrl string // gravatar url
}

Gravatar is detail about the Gravatar

type LookupError 

type LookupError struct {
	Message string `json:"message" xml:"message"`
	Details string `json:"details" xml:"details"`
}

LookupError is an MX dns records lookup error

func ParseSMTPError 

func ParseSMTPError(err error) *LookupError

ParseSMTPError receives an MX Servers response message and generates the corresponding MX error

func (*LookupError) Error 

func (e *LookupError) Error() string

type Mx 

type Mx struct {
	HasMXRecord bool      // whether has 1 or more MX record
	Records     []*net.MX // represent DNS MX records
}

Mx is detail about the Mx host

type Result 

type Result struct {
	Email        string    `json:"email"`          // passed email address
	Reachable    string    `json:"reachable"`      // an enumeration to describe whether the recipient address is real
	Syntax       Syntax    `json:"syntax"`         // details about the email address syntax
	SMTP         *SMTP     `json:"smtp"`           // details about the SMTP response of the email
	Gravatar     *Gravatar `json:"gravatar"`       // whether or not have gravatar for the email
	Suggestion   string    `json:"suggestion"`     // domain suggestion when domain is misspelled
	Disposable   bool      `json:"disposable"`     // is this a DEA (disposable email address)
	RoleAccount  bool      `json:"role_account"`   // is account a role-based account
	Free         bool      `json:"free"`           // is domain a free email domain
	HasMxRecords bool      `json:"has_mx_records"` // whether or not MX-Records for the domain
}

Result is the result of Email Verification

type SMTP 

type SMTP struct {
	HostExists  bool `json:"host_exists"` // is the host exists?
	FullInbox   bool `json:"full_inbox"`  // is the email account's inbox full?
	CatchAll    bool `json:"catch_all"`   // does the domain have a catch-all email address?
	Deliverable bool `json:"deliverable"` // can send an email to the email server?
	Disabled    bool `json:"disabled"`    // is the email blocked or disabled by the provider?
}

SMTP stores all information for SMTP verification lookup

type Syntax 

type Syntax struct {
	Username string `json:"username"`
	Domain   string `json:"domain"`
	Valid    bool   `json:"valid"`
}

Syntax stores all information about an email Syntax

type Verifier 

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

Verifier is an email verifier. Create one by calling NewVerifier

func NewVerifier 

func NewVerifier() *Verifier

NewVerifier creates a new email verifier

func NewVerifierWithEmailAndName added in v0.0.4 

func NewVerifierWithEmailAndName(email, name string) *Verifier

NewVerifier creates a new email verifier

func (*Verifier) AddDisposableDomains 

func (v *Verifier) AddDisposableDomains(domains []string) *Verifier

AddDisposableDomains adds additional domains as disposable domains.

func (*Verifier) CheckCatchAll added in v0.0.4 

func (v *Verifier) CheckCatchAll(domain string, ret *SMTP) error

Checks the deliver ability of a randomly generated address in order to verify the existence of a catch-all and etc.

func (*Verifier) CheckGravatar 

func (v *Verifier) CheckGravatar(email string) (*Gravatar, error)

CheckGravatar will return the Gravatar records for the given email.

func (*Verifier) CheckMX 

func (v *Verifier) CheckMX(domain string) (*Mx, error)

CheckMX will return the DNS MX records for the given domain name sorted by preference.

func (*Verifier) CheckSMTP 

func (v *Verifier) CheckSMTP(domain, username string) (*SMTP, error)

CheckSMTP performs an email verification on the passed domain via SMTP

  • the domain is the passed email domain
  • username is used to check the deliverability of specific email address,

if server is catch-all server, username will not be checked

func (*Verifier) CheckSMTPPresence added in v0.0.4 

func (v *Verifier) CheckSMTPPresence(domain, username string, ret *SMTP) error

func (*Verifier) DisableAutoUpdateDisposable 

func (v *Verifier) DisableAutoUpdateDisposable() *Verifier

DisableAutoUpdateDisposable stops previously started schedule job

func (*Verifier) DisableDomainSuggest 

func (v *Verifier) DisableDomainSuggest() *Verifier

DisableDomainSuggest will not suggest anything

func (*Verifier) DisableGravatarCheck 

func (v *Verifier) DisableGravatarCheck() *Verifier

DisableGravatarCheck disables check gravatar,

func (*Verifier) DisableSMTPCheck 

func (v *Verifier) DisableSMTPCheck() *Verifier

DisableSMTPCheck disables check email by smtp

func (*Verifier) EnableAutoUpdateDisposable 

func (v *Verifier) EnableAutoUpdateDisposable() *Verifier

EnableAutoUpdateDisposable enables update disposable domains automatically

func (*Verifier) EnableDomainSuggest 

func (v *Verifier) EnableDomainSuggest() *Verifier

EnableDomainSuggest will suggest a most similar correct domain when domain misspelled

func (*Verifier) EnableGravatarCheck 

func (v *Verifier) EnableGravatarCheck() *Verifier

EnableGravatarCheck enables check gravatar, we don't check gravatar by default

func (*Verifier) EnableSMTPCheck 

func (v *Verifier) EnableSMTPCheck() *Verifier

EnableSMTPCheck enables check email by smtp, for most ISPs block outgoing SMTP requests through port 25, to prevent spam, we don't check smtp by default

func (*Verifier) FromEmail 

func (v *Verifier) FromEmail(email string) *Verifier

FromEmail sets the emails to use in the `MAIL FROM:` smtp command

func (*Verifier) GetClient added in v0.0.4 

func (v *Verifier) GetClient(domain string) (*smtp.Client, error)

Create a new client which is connected to the SMTP server awaiting RCPT

func (*Verifier) HelloName 

func (v *Verifier) HelloName(domain string) *Verifier

HelloName sets the name to use in the `EHLO:` SMTP command

func (*Verifier) IsDisposable 

func (v *Verifier) IsDisposable(domain string) bool

IsDisposable checks if domain is a disposable domain

func (*Verifier) IsFreeDomain 

func (v *Verifier) IsFreeDomain(domain string) bool

IsFreeDomain checks if domain is a free domain

func (*Verifier) IsRoleAccount 

func (v *Verifier) IsRoleAccount(username string) bool

IsRoleAccount checks if username is a role-based account

func (*Verifier) ParseAddress 

func (v *Verifier) ParseAddress(email string) Syntax

ParseAddress attempts to parse an email address and return it in the form of an Syntax

func (*Verifier) Proxy 

func (v *Verifier) Proxy(proxyURI string) *Verifier

Proxy sets a SOCKS5 proxy to verify the email, proxyURI should be in the format: "socks5://user:password@127.0.0.1:1080?timeout=5s". The protocol could be socks5, socks4 and socks4a.

func (*Verifier) SuggestDomain 

func (v *Verifier) SuggestDomain(domain string) string

SuggestDomain checks if domain has a typo and suggests a similar correct domain from metadata, returns a suggestion

func (*Verifier) Verify 

func (v *Verifier) Verify(email string) (*Result, error)

Verify performs address, misc, mx and smtp checks

Source Files

View all Source files

Directories

Path Synopsis
cmd
apiserver
build_metadata

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.