Package email checks an address against the Mailbox grammar of
RFC 5321, the production an
address must satisfy to appear in an SMTP MAIL or RCPT command.
Validators commonly approximate this grammar with a regular
expression; this package implements it directly, along with the length
limits and errata that accompany it.
- The RFC 5321
Mailboxgrammar: dot-string and quoted-string local parts, letter-digit-hyphen domain labels, and IPv4 and IPv6 address literals. - Length limits from RFC 5321 section 4.5.3.1 as corrected by RFC 3696 erratum 1690: a 64-octet local part, a 255-octet domain, and a 254-octet address.
- With
ValidateSMTPUTF8, the internationalization extensions of RFC 6531 and RFC 6532: well-formed UTF-8 in the local part and IDNA2008 U-labels in the domain, including the RFC 5892 derived-property and contextual rules.
Validation is syntactic. The package does not resolve DNS, apply IDN registry policy, or confirm that a mailbox exists. SPEC.md records the governing specifications, the rules enforced, and the judgment calls behind them.
go get github.com/initialcapacity/email-address-validatorThe import path ends in email-address-validator; the package name is
email:
import email "github.com/initialcapacity/email-address-validator"Validate and ValidateSMTPUTF8 return nil for a valid address.
IsValid and IsValidSMTPUTF8 are boolean forms of the same checks.
iferr:=email.Validate("grace.hopper@example.com"); err!=nil {
log.Fatal(err)
}
email.IsValid("用户@example.com") // false: non-ASCII requires SMTPUTF8email.IsValidSMTPUTF8("用户@example.com") // trueEvery failure is a *email.SyntaxError wrapping a sentinel error.
Classify failures with errors.Is, then recover the byte offset of the
fault with errors.As:
err:=email.Validate("ada@exa_mple.com")
iferrors.Is(err, email.ErrInvalidDomain) {
varsyntaxErr*email.SyntaxErroriferrors.As(err, &syntaxErr) {
fmt.Println(syntaxErr.Offset) // 7, the underscore
}
}The package documentation lists the sentinel errors and holds runnable examples.
The repository doubles as a porting kit. REIMPLEMENTING.md lists what a port needs, and testdata/cases.json holds a language-agnostic conformance suite that CI runs against this implementation.
To start a port, give a coding agent this prompt, filling in the language:
Reimplement the email address validator from https://github.com/initialcapacity/email-address-validator in
<language>. Clone or fetch the repository, then read REIMPLEMENTING.md, SPEC.md, and testdata/README.md, in that order, along with the RFC sections they cite. The Go source is the reference implementation.Implement both validation modes: strict RFC 5321 (ASCII) and RFC 6531 (SMTPUTF8). Expose a boolean check and a diagnostic form that reports an error kind and a byte offset. Accept byte-string input so the base64-encoded cases run.
Write a conformance test that runs every case in testdata/cases.json through both modes, and iterate until both tiers pass in full: the accept/reject results must match
valid.asciiandvalid.smtputf8, and the diagnostics must match everyerrorsentry, kind and offset. Fix the implementation, never the expectations, and do not special-case any vector. Use idiomatic tooling and project structure for<language>, and keep third-party dependencies to what the standard library cannot provide.
Build and test with the standard Go toolchain, version 1.27 or later:
go build ./...
go test -race ./...Before sending a change, run the same checks CI runs:
test -z "$(gofmt -l .)"
go vet ./...
go test -race ./...unicode_tables.go holds case folding, Joining_Type, and virama data
generated from the Unicode Character Database. A test fails when its
version drifts from the standard library's; after a toolchain upgrade,
regenerate it:
go run gen_unicode_tables.go -ucd /path/to/ucd -version 17.0.0A fuzz target exercises the parser with arbitrary input and asserts that RFC 5321 validity implies RFC 6531 validity. CI runs it for 30 seconds; run it longer when changing the parser:
go test -fuzz=FuzzValidate -fuzztime=5m .MIT; see LICENSE.