zerobounce

README

ZeroBounce Email Verification Library for Go

Getting Started

You will need a zerobounce account to get started.
Once you get an account, you will need to get an api key to use it in the API calls.

Installation

Require the package

$ go get https://github.com/twisted1919/zerobounce-go

Go Version

Requires Go >= 1.8

Usage

package main

import (
	"fmt"
	"github.com/twisted1919/zerobounce-go"
	"log"
	"net/netip"
)

// Example function to show available credits
func credits(api *zerobounce.API) {
	response, err := api.GetCredits()
	if err != nil {
		log.Fatal(fmt.Errorf("unable to fetch the credits: %w", err))
	}

	if response.IsSuccess() {
		fmt.Println("you have", response.Success.Credits, "credits left")
	} else if response.IsError() {
		fmt.Println("the api returned following error", response.Error.Error)
	}
}

// Example function to validate an email address
func validate(api *zerobounce.API, email string, ipAddress *netip.Addr) {
	response, err := api.Validate(email, ipAddress)
	if err != nil {
		log.Fatal(fmt.Errorf("unable to validate email address: %w", err))
	}

	if response.IsSuccess() {
		fmt.Println("the email address", email, "is", response.Success.Status)
	} else if response.IsError() {
		fmt.Println("the api returned following error", response.Error.Error)
	}
}

func main() {

	// instantiate the api
	api := zerobounce.NewAPI("your-api-key")

	// output the result of validation call for a valid email address
	validate(api, "valid@example.com", nil)

	// output the result of validation call for an invalid email address
	validate(api, "invalid@example.com", nil)

	// output the result of validation call for an valid email address but for a different IP Address
	ipAddress := netip.MustParseAddr("127.0.0.1")
	validate(api, "valid@example.com", &ipAddress)

	// output the result of the get credits call
	credits(api)

}

License

MIT

Test

Set your api key in the ZEROBOUNCE_API_KEY environment variable, then run:

$ go test ./...

Bug Reports

Report here.

Documentation

Index

• Constants
• type API
  • func NewAPI(apiKey string) *API
  • func (a *API) GetAPIKey() string
  • func (a *API) GetAPIURL() string
  • func (a *API) GetCredits() (*ResponseType[CreditsResponseSuccess], error)
  • func (a *API) SetAPIKey(key string) *API
  • func (a *API) SetAPIURL(url string) *API
  • func (a *API) Validate(email string, ipAddress *netip.Addr) (*ResponseType[ValidateResponseSuccess], error)
• type CreditsResponseSuccess
  • func (c *CreditsResponseSuccess) AsInt() int
• type ResponseError
• type ResponseType
  • func (r *ResponseType[T]) IsError() bool
  • func (r *ResponseType[T]) IsSuccess() bool
• type ValidateResponseSuccess
  • func (r *ValidateResponseSuccess) IsAbuse() bool
  • func (r *ValidateResponseSuccess) IsCatchAll() bool
  • func (r *ValidateResponseSuccess) IsDoNotMail() bool
  • func (r *ValidateResponseSuccess) IsInvalid() bool
  • func (r *ValidateResponseSuccess) IsSpamtrap() bool
  • func (r *ValidateResponseSuccess) IsUnknown() bool
  • func (r *ValidateResponseSuccess) IsValid() bool

Constants

const (
	APIURL = "https://api.zerobounce.net/v2"
)

Types

type API

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

func NewAPI

func NewAPI(apiKey string) *API

func (*API) GetAPIKey

func (a *API) GetAPIKey() string

func (*API) GetAPIURL

func (a *API) GetAPIURL() string

func (*API) GetCredits

func (a *API) GetCredits() (*ResponseType[CreditsResponseSuccess], error)

func (*API) SetAPIKey

func (a *API) SetAPIKey(key string) *API

func (*API) SetAPIURL

func (a *API) SetAPIURL(url string) *API

func (*API) Validate

func (a *API) Validate(email string, ipAddress *netip.Addr) (*ResponseType[ValidateResponseSuccess], error)

type CreditsResponseSuccess

type CreditsResponseSuccess struct {
	Credits string `json:"Credits"` //nolint:tagliatelle
}

func (*CreditsResponseSuccess) AsInt

func (c *CreditsResponseSuccess) AsInt() int

type ResponseError

type ResponseError struct {
	Error string `json:"error"`
}

type ResponseType

type ResponseType[T CreditsResponseSuccess | ValidateResponseSuccess] struct {
	Success *T
	Error   *ResponseError
}

func (*ResponseType[T]) IsError

func (r *ResponseType[T]) IsError() bool

func (*ResponseType[T]) IsSuccess

func (r *ResponseType[T]) IsSuccess() bool

type ValidateResponseSuccess

type ValidateResponseSuccess struct {
	// The email address you are validating.
	Address string
	// [valid, invalid, catch-all, unknown, spamtrap, abuse, do_not_mail]
	Status string
	//nolint:lll    // [antispam_system, greylisted, mail_server_temporary_error, forcible_disconnect, mail_server_did_not_respond, timeout_exceeded, failed_smtp_connection, mailbox_quota_exceeded, exception_occurred, possible_trap, role_based, global_suppression, mailbox_not_found, no_dns_entries, failed_syntax_check, possible_typo, unroutable_ip_address, leading_period_removed, does_not_accept_mail, alias_address, role_based_catch_all, disposable, toxic]
	SubStatus string `json:"sub_status"` //nolint:tagliatelle
	// [true/false] If the email comes from a free provider.
	FreeEmail bool `json:"free_email"` //nolint:tagliatelle
	// Suggestive Fix for an email typo
	DidYouMean *string `json:"did_you_mean"` //nolint:tagliatelle
	// The portion of the email address before the "@" symbol or null.
	Account *string `json:"account"`
	// The portion of the email address after the "@" symbol or null.
	Domain *string `json:"domain"`
	// Age of the email domain in days or [null].
	DomainAgeDays *string `json:"domain_age_days"` //nolint:tagliatelle
	// The SMTP Provider of the email or [null] [BETA].
	SMTPProvider *string `json:"smtp_provider"` //nolint:tagliatelle
	// The preferred MX record of the domain
	MxRecord *string `json:"mx_record"` //nolint:tagliatelle
	// [true/false] Does the domain have an MX record. [they return "bool" not bool, which makes it a string...]
	MxFound *string `json:"mx_found"` //nolint:tagliatelle
	// The first name of the owner of the email when available or [null].
	Firstname *string `json:"firstname"`
	// The last name of the owner of the email when available or [null].
	Lastname *string `json:"lastname"`
	// The gender of the owner of the email when available or [null].
	Gender *string `json:"gender"`
	// The country of the IP passed in or [null]
	Country *string `json:"country"`
	// The region/state of the IP passed in or [null]
	Region *string `json:"region"`
	// The city of the IP passed in or [null]
	City *string `json:"city"`
	// The zipcode of the IP passed in or [null]
	Zipcode *string `json:"zipcode"`
	// The UTC time the email was validated.
	ProcessedAt string `json:"processed_at"` //nolint:tagliatelle
}

func (*ValidateResponseSuccess) IsAbuse

func (r *ValidateResponseSuccess) IsAbuse() bool

func (*ValidateResponseSuccess) IsCatchAll

func (r *ValidateResponseSuccess) IsCatchAll() bool

func (*ValidateResponseSuccess) IsDoNotMail

func (r *ValidateResponseSuccess) IsDoNotMail() bool

func (*ValidateResponseSuccess) IsInvalid

func (r *ValidateResponseSuccess) IsInvalid() bool

func (*ValidateResponseSuccess) IsSpamtrap

func (r *ValidateResponseSuccess) IsSpamtrap() bool

func (*ValidateResponseSuccess) IsUnknown

func (r *ValidateResponseSuccess) IsUnknown() bool

func (*ValidateResponseSuccess) IsValid

func (r *ValidateResponseSuccess) IsValid() bool