email

README

go-email

go-email provides conservative email address validation, normalization helpers, MIME message rendering, and small delivery backends.

The root module is:

go get github.com/tavocg/go-email

The Mailgun backend is published as a separate module:

go get github.com/tavocg/go-email/mailer/backends/mailgun

Requirements

This project requires Go 1.24.0 or newer.

Email Validation

Use StrictParser when you want a conservative ASCII-only address format for storage, account identifiers, or comparisons.

address, err := email.StrictParser("User.Name+signup@Example.com")
if err != nil {
	return err
}

address.Normalize()
fmt.Println(address.Address()) // user.name+signup@example.com

The strict parser trims surrounding whitespace and rejects addresses outside the package's documented format. It does not check DNS, deliverability, real TLDs, or provider-specific address rules.

Normalize lowercases the full address. Apply it consistently anywhere addresses are stored or compared.

Plus-tag stripping is provider-specific, so it is explicit:

address.Normalize(email.StripPlusTag())

Blacklist Checks

ValidAddress.IsBlacklisted checks the address domain against a custom list or, when no list is provided, the embedded disposable-domain list.

blocked := address.IsBlacklisted([]string{"example.com"})

MIME Messages

The mailer package builds MIME bytes suitable for SMTP DATA or HTTP API backends.

message := mailer.NewAlternativeMessage(
	"sender@example.com",
	[]string{"recipient@example.com"},
	"Welcome",
	"Welcome to the service.",
	"<p>Welcome to the service.</p>",
)
message.AttachWithType("hello.txt", "text/plain", []byte("hello\n"))

data, err := message.Bytes()
if err != nil {
	return err
}

Message rendering rejects CR or LF characters in header and envelope fields and returns mailer.ErrInvalidHeader.

SMTP

The SMTP backend supports implicit TLS and STARTTLS. NewClient validates the address and configures TLS without touching the network. Use CheckTransport when you want an explicit startup probe.

client, err := smtpbackend.NewClient(
	"smtp.example.com:587",
	"username",
	"password",
	smtpbackend.WithStartTLS(),
)
if err != nil {
	return err
}

if err := client.CheckTransport(ctx); err != nil {
	return err
}

err = client.Send(ctx, message)

Mailgun

The Mailgun backend uses Mailgun's HTTP API and accepts rendered MIME messages from the shared mailer.Message type.

client, err := mailgun.NewClient("mg.example.com", apiKey)
if err != nil {
	return err
}

err = client.Send(ctx, message)

Examples

Runnable examples are available under examples/:

• examples/validation
• examples/message
• examples/smtp

License

GNU General Public License v3.0. See LICENSE.

Documentation

Overview

Package email validates and normalizes email addresses for storage and comparison.

Index

• Constants
• type NormalizeOption
  • func StripPlusTag() NormalizeOption
• type ValidAddress
  • func StrictParser(email string) (valid *ValidAddress, err error)
  • func (v *ValidAddress) Address() string
  • func (v *ValidAddress) IsBlacklisted(blacklists ...[]string) bool
  • func (v *ValidAddress) Normalize(options ...NormalizeOption)

Constants

const StrictParserError = errStr("email does not meet StrictParser requirements")

Types

type NormalizeOption

type NormalizeOption func(*normalizeConfig)

NormalizeOption configures optional normalization behavior.

func StripPlusTag

func StripPlusTag() NormalizeOption

StripPlusTag removes everything after the first "+" in the local part during normalization.

type ValidAddress

type ValidAddress string

ValidAddress is an email address that has already passed package validation.

It exists so Normalize can be limited to addresses returned by the package parsers instead of arbitrary strings.

func StrictParser

func StrictParser(email string) (valid *ValidAddress, err error)

StrictParser trims surrounding whitespace and validates the address against the package's strict rules.

func (*ValidAddress) Address

func (v *ValidAddress) Address() string

func (*ValidAddress) IsBlacklisted

func (v *ValidAddress) IsBlacklisted(blacklists ...[]string) bool

IsBlacklisted reports whether the receiver's domain matches any blacklist entry. When no custom blacklist is provided, it falls back to DefaultBlacklist.

func (*ValidAddress) Normalize

func (v *ValidAddress) Normalize(options ...NormalizeOption)

Normalize canonicalizes the receiver for storage and comparison.

Apply the same normalization anywhere the address is stored, matched, or used for verification so those operations stay consistent.