github.com/go-email-validator/go-email-validator@v0.0.0-20230409163946-b8b9e6a0552e/Readme.md (about)

     1  [![Go Reference](https://pkg.go.dev/badge/github.com/go-email-validator/go-email-validator.svg)](https://pkg.go.dev/github.com/go-email-validator/go-email-validator)
     2  [![codecov](https://codecov.io/gh/go-email-validator/go-email-validator/branch/master/graph/badge.svg?token=BC864E3W3X)](https://codecov.io/gh/go-email-validator/go-email-validator)
     3  [![Go Report](https://goreportcard.com/badge/github.com/go-email-validator/go-email-validator)](https://goreportcard.com/report/github.com/go-email-validator/go-email-validator)
     4  
     5  ## Library under development (Interfaces may be changed slightly)
     6  
     7  ## Demo on [rapidapi.com](https://rapidapi.com/maranqz/api/email-validator15)
     8  
     9  ## Install
    10  
    11  ```go get -u github.com/go-email-validator/go-email-validator```
    12  
    13  ## Available validators
    14  
    15  username@domain.part
    16  
    17  * [syntaxValidator](pkg/ev/validator_syntax.go)
    18    1. `NewSyntaxValidator()` - mail.ParseAddress from built-in library
    19    1. `NewSyntaxRegexValidator(emailRegex *regexp.Regexp)` - validation based on regular expression
    20  * [disposableValidator](pkg/ev/validator_disposable.go) based
    21    on [mailchecker](https://github.com/FGRibreau/mailchecker) by default (set is replaceable)
    22  * [roleValidator](pkg/ev/validator_role.go) bases on [role-based-email-addresses](https://github.com/mixmaxhq/role-based-email-addresses) by default (set is replaceable)
    23  * [mxValidator](pkg/ev/validator_mx.go)
    24  * [smtpValidator](pkg/ev/validator_smtp.go)
    25  
    26      to use proxy connection, DialFunc need to be changed in [Checker](pkg/ev/evsmtp/smtp.go). There is [evsmtp.H12IODial](pkg/ev/evsmtp/proxy.go), implementing for [h12w](https://github.com/h12w/socks).
    27  * [banWordsUsernameValidator](pkg/ev/validator_banwords_username.go) looks for banned words in username
    28  * [blackListEmailsValidator](pkg/ev/validator_blacklist_email.go) blocked emails from list
    29  * [blackListValidator](pkg/ev/validator_blacklist_domain.go) blocked emails with domains from black list
    30  * [whiteListValidator](pkg/ev/validator_whitelist_domain.go) accepts only emails from white list
    31  * [gravatarValidator](pkg/ev/validator_gravatar.go) check existing of user on gravatar.com
    32  
    33  ## Usage
    34  
    35  ### With builder
    36  
    37  ```go
    38  package main
    39  
    40  import (
    41    "fmt"
    42    "github.com/go-email-validator/go-email-validator/pkg/ev"
    43    "github.com/go-email-validator/go-email-validator/pkg/ev/evmail"
    44  )
    45  
    46  func main() {
    47    // create defaults DepValidator with GetDefaultFactories() as list of validators
    48    builder := ev.NewDepBuilder(nil).Build()
    49    /*
    50       to set another list of initial validators
    51       builder := NewDepBuilder(&ValidatorMap{
    52           ev.ValidatorName: ev.Validator,
    53       }).Build()
    54    */
    55  
    56    // builder.Set(ev.ValidatorName, NewValidator()) builder
    57    // builder.Has(names ...ev.ValidatorName) bool
    58    // builder.Delete(names ...ev.ValidatorName) bool
    59  
    60    validator := builder.Build()
    61  
    62    v := validator.Validate(NewInput(evmail.FromString("test@evmail.com")))
    63    if !v.IsValid() {
    64      panic("email is invalid")
    65    }
    66  
    67    fmt.Println(v)
    68  }
    69  
    70  ```
    71  
    72  ### Single validator
    73  
    74  ```go
    75  package main
    76  
    77  import (
    78    "fmt"
    79    "github.com/go-email-validator/go-email-validator/pkg/ev"
    80    "github.com/go-email-validator/go-email-validator/pkg/ev/evmail"
    81  )
    82  
    83  func main() {
    84    var v = ev.NewSyntaxValidator().Validate(ev.NewInput(evmail.FromString("some@evmail.here"))) // ev.ValidationResult
    85  
    86    if !v.IsValid() {
    87      panic("email is invalid")
    88    }
    89  
    90    fmt.Println(v)
    91  }
    92  ```
    93  
    94  ### Addition options
    95  
    96  To set options for different validators, use NewInput(..., NewKVOption(ValidatorName, Options))
    97  
    98  ```go
    99  NewInput(
   100  	evmail.FromString("test@evmail.com"), 
   101  	NewKVOption(SMTPValidatorName, evsmtp.NewOptions(evsmtp.OptionsDTO{
   102  		Port: 465,
   103      })),
   104  )
   105  ```
   106  
   107  Use function New...(...) to create structure instead of public.
   108  
   109  ## How to extend
   110  
   111  To add own validator, just implement [ev.Validator](pkg/ev/validator.go) interface. For validator without dependencies, you can use structure ev.AValidatorWithoutDeps
   112  
   113  ## Decorators
   114  
   115  1. [WarningsDecorator](pkg/ev/decorator_warnings.go) allows moving errors to warnings and change result of `IsValid()` in [ValidationResult](pkg/ev/validator.go).
   116  1. Cache based on evcahce.Interface, default realization is done for gocache.
   117      * [CacheDecorator](pkg/ev/decorator_cache.go) saves result of validator. For caching, you can implement `evcache.Interface` or use [gocache implementation](https://github.com/eko/gocache) by `evcache.NewCache`. See [Test_Cache](pkg/ev/decorator_cache_test.go) as example.
   118      * [checkerCacheRandomRCPT](pkg/ev/evsmtp/smtp.go) for caching of RandomRCPTs request. See Test_checkerCacheRandomRCPT_RandomRCPT_RealCache as example.
   119  
   120  **Notice**, to use [msgpack](https://github.com/vmihailenco/msgpack) you should have exported fields or implement custom encoding/decoding ([doc](https://msgpack.uptrace.dev/#custom-encodingdecoding))
   121  
   122  ## Logger
   123  
   124  Package use [zap](https://github.com/uber-go/zap).
   125  
   126  To use logging see in [log package](pkg/log).
   127  Default level is zap.ErrorLevel.
   128  
   129  ## Addition
   130  
   131  1. For running workflow locally use [act](https://github.com/nektos/act)
   132  
   133  ## FAQ
   134  
   135  #### Most Internet Service Providers block outgoing SMTP request.
   136  
   137  The [StackOverflow thread](https://stackoverflow.com/questions/18139102/how-to-get-around-an-isp-block-on-port-25-for-smtp) could be helpful.
   138  
   139  #### To check smtp in telnet
   140  
   141  ```
   142  telnet
   143  
   144  OPEN gmail-smtp-in.l.google.com 25
   145  EHLO localhost
   146  MAIL FROM: <user@example.org>
   147  rcpt to: <some.email@gmail.com>
   148  quit
   149  ```
   150  
   151  #### Some mail providers could put your ip in spam filter.
   152  
   153  For example:
   154  1. hotmail.com
   155  
   156  ## Roadmap
   157  
   158  * Tests
   159    * Add functional tests
   160    * Find way to compare functions in tests
   161  * Add binary release
   162  * Check in spamhaus
   163  * Add misspelled email
   164  * Add DKIM checking
   165  * Add linter in pre-hook and ci
   166  * Do full thread safe library
   167  * Copy features from [truemail](https://github.com/truemail-rb/truemail)
   168      * [Extend MX](https://truemail-rb.org/truemail-gem/#/validations-layers?id=mx-validation)
   169        , [rfc5321 section 5](https://tools.ietf.org/html/rfc5321#section-5)
   170      * [Host audit features](https://truemail-rb.org/truemail-gem/#/host-audit-features)
   171  
   172  ## Inspired by
   173  
   174  * [EmailValidator](https://github.com/egulias/EmailValidator)