adapter

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package adapter is the contract every address verification service implements (ZeroBounce, NeverBounce, Kickbox, Bouncer, Emailable), like internal/providers is for sending providers: a descriptor with the service's capabilities and the codes it answers, plain HTTP calls with the workspace's own API key, and answers mapped to ReputeCast's four results with the service's own code kept beside them.

Adapters live in internal/verification/adapter/<name>, register themselves from init and pass the shared suite in internal/verification/adapter/contracttest. Core code finds them through Lookup and never imports one.

Index

Constants

View Source
const (
	ReasonInvalidAddress = "invalid_address"
	ReasonSpamTrap       = "spam_trap"
	ReasonCatchAll       = "catch_all"
	ReasonRole           = "role"
	ReasonDisposable     = "disposable"
)

Reasons. Invalid answers are either an address that can't receive mail or a (possible) spam trap; risky ones say why. A service's own reason that fits none of these is kept as it is ("abuse", "toxic").

Variables

View Source
var (
	// ErrAuth means the service rejected the API key.
	ErrAuth = errors.New("the service rejected the API key")
	// ErrNoCredits means the account has no credits left.
	ErrNoCredits = errors.New("the service has no credits left")
	// ErrRateLimited means the service asked to slow down (429 and the like).
	ErrRateLimited = errors.New("the service asked to slow down")
	// ErrUnavailable means the service didn't answer or answered 5xx.
	ErrUnavailable = errors.New("the service isn't answering")
)

Errors an adapter returns, so jobs know whether to stop, pause or retry.

View Source
var ErrRefused = errors.New("the service refused the request")

ErrRefused means the service refused the request for another reason (a malformed request); retrying won't help.

View Source
var Order = []string{"zerobounce", "kickbox", "neverbounce", "bouncer", "emailable"}

Order is the catalog's order of the services the brief names.

Functions

func Classify

func Classify(status int, header http.Header, body []byte, noCredits func(status int, body []byte) bool) error

Classify maps a non-2xx answer to the adapter errors. noCredits tells a service's "out of credits" answers apart when it shares a status with another error (Kickbox answers 403 for both a bad key and no balance).

func Decode

func Decode(resp *Response, v any) error

Decode reads a JSON answer into v; a body that isn't JSON is an ErrUnavailable (proxies answer HTML pages).

func Register

func Register(d Descriptor)

Register adds a service. Adapters call it from init.

func Status

func Status(err error) int

Status is the HTTP status in err, or 0.

func Temporary

func Temporary(err error) bool

Temporary reports whether a later retry may succeed (rate limits, outages).

Types

type Adapter

type Adapter interface {
	// Balance reads the account's credit balance. It sends no address.
	Balance(ctx context.Context) (int64, error)
	// Verify checks one address within timeout (real-time checks, one
	// contact, and bulk jobs one by one).
	Verify(ctx context.Context, email string, timeout time.Duration) (Answer, error)
	// VerifyBatch checks up to Descriptor.MaxBatch addresses in one go and
	// returns one answer per address, in order. Services without a batch
	// endpoint check them one by one inside.
	VerifyBatch(ctx context.Context, emails []string) ([]Answer, error)
}

Adapter calls one service with one account's key.

type Answer

type Answer struct {
	Email  string
	Result Result
	// Reason is set for invalid and risky answers (see the Reason constants).
	Reason string
	// Code is the service's own answer, as the service words it
	// ("invalid / mailbox_not_found", "catch-all"), kept beside the result
	// the way bounce codes are.
	Code string
}

Answer is a service's verdict on one address.

func OneByOne

func OneByOne(ctx context.Context, emails []string, parallel int, verify func(ctx context.Context, email string) (Answer, error)) ([]Answer, error)

OneByOne checks emails with verify, up to parallel at a time, and returns the answers in order. The first error stops it; answers before it are returned with the error so a job keeps them. An error stops only the addresses after the one that failed: checks of the addresses before it run to the end, however late they are, since the service answers (and charges for) them whatever order the parallel checks reach it in.

func (Answer) Tag

func (a Answer) Tag() string

Tag is the contact tag a risky or unknown answer gets ("verify:catch-all").

type CallError

type CallError struct {
	Kind    error
	Status  int
	Message string
	// RetryAfter is the wait the service asked for (Retry-After), when it did.
	RetryAfter time.Duration
}

CallError carries the HTTP status and the service's message with one of the errors above.

func (*CallError) Error

func (e *CallError) Error() string

func (*CallError) Unwrap

func (e *CallError) Unwrap() error

type Capabilities

type Capabilities struct {
	BulkLists     bool `json:"bulkLists"`
	RealTime      bool `json:"realTime"`
	CatchAll      bool `json:"catchAll"`
	CreditBalance bool `json:"creditBalance"`
	// DataRegion is true when the account can choose where addresses are
	// processed (ZeroBounce: United States or the EU).
	DataRegion bool `json:"dataRegion"`
}

Capabilities are the badges the catalog shows for a service.

type Config

type Config struct {
	APIKey string
	// Region selects the data region where the service has several ("us",
	// "eu"); empty uses its default endpoint.
	Region string
	// BaseURL replaces the service's API address (tests and recordings).
	BaseURL    string
	HTTPClient *http.Client
}

Config opens an adapter for one connected service.

func (Config) Client

func (c Config) Client() *http.Client

Client returns the HTTP client to use (a default with a timeout when unset).

type Descriptor

type Descriptor struct {
	Key  string `json:"key"`
	Name string `json:"name"`
	// Initials are the logo tile's letters ("ZB").
	Initials     string       `json:"initials"`
	Capabilities Capabilities `json:"capabilities"`
	Regions      []Region     `json:"regions"`
	// DefaultRegion is where addresses go when no region is chosen
	// ("United States"); empty when the service doesn't say.
	DefaultRegion string `json:"defaultRegion"`
	// Website is the service's own site (Add credits, Open ZeroBounce) and
	// KeyHelp where its API keys are created.
	Website string `json:"website"`
	KeyHelp string `json:"keyHelp"`
	// MaxBatch is how many addresses VerifyBatch takes at once.
	MaxBatch int `json:"maxBatch"`
	// PerSecond paces bulk jobs below the service's rate limits.
	PerSecond float64   `json:"perSecond"`
	Mappings  []Mapping `json:"mappings"`
	New       func(Config) (Adapter, error)
}

Descriptor describes a service in the catalog.

func Catalog

func Catalog() []Descriptor

Catalog returns every registered service: the brief's in its order, then any other alphabetically.

func Lookup

func Lookup(key string) (Descriptor, bool)

Lookup returns a registered service.

type Mapping

type Mapping struct {
	Codes  []string `json:"codes"`
	Result Result   `json:"result"`
	Reason string   `json:"reason,omitempty"`
}

Mapping is one row of "How <service>'s answers map": the service's codes, the result and reason they become.

type Region

type Region struct {
	Key   string `json:"key"`
	Label string `json:"label"`
}

Region is a data region a service offers.

type Request

type Request struct {
	Method string
	URL    string
	Query  url.Values
	Header http.Header
	// Body is sent as JSON when set.
	Body any
}

Request is one call to a service's JSON API.

type Response

type Response struct {
	Status int
	Header http.Header
	Body   []byte
}

Response is a 2xx answer.

func Do

func Do(ctx context.Context, hc *http.Client, req Request, noCredits func(status int, body []byte) bool) (*Response, error)

Do sends req and returns a 2xx answer, or an error from Classify. Network failures and timeouts are ErrUnavailable.

type Result

type Result string

Result is one of the four outcomes every service's answer maps to.

const (
	Valid   Result = "valid"
	Invalid Result = "invalid"
	Risky   Result = "risky"
	Unknown Result = "unknown"
)

Results.

Directories

Path Synopsis
Package bouncer checks addresses with Bouncer's v1.1 API (https://docs.usebouncer.com): GET /v1.1/credits and GET /v1.1/email/verify, authenticated with the x-api-key header.
Package bouncer checks addresses with Bouncer's v1.1 API (https://docs.usebouncer.com): GET /v1.1/credits and GET /v1.1/email/verify, authenticated with the x-api-key header.
Package contracttest is the shared suite every verification service adapter passes, like the sending adapters' suite: registration and capabilities, the balance (which sends no address), each of the four results with the service's own code, batches in order, and the errors jobs act on (a rejected key, no credits, rate limits, an outage), against a fake of the service's API that serves recorded answers.
Package contracttest is the shared suite every verification service adapter passes, like the sending adapters' suite: registration and capabilities, the balance (which sends no address), each of the four results with the service's own code, batches in order, and the errors jobs act on (a rejected key, no credits, rate limits, an outage), against a fake of the service's API that serves recorded answers.
Package emailable checks addresses with Emailable's v1 API (https://emailable.com/docs/api): GET /v1/account and GET /v1/verify with the key as api_key.
Package emailable checks addresses with Emailable's v1 API (https://emailable.com/docs/api): GET /v1/account and GET /v1/verify with the key as api_key.
Package kickbox checks addresses with Kickbox's v2 API (https://docs.kickbox.com): GET /v2/verify and GET /v2/balance with the key as the apikey parameter.
Package kickbox checks addresses with Kickbox's v2 API (https://docs.kickbox.com): GET /v2/verify and GET /v2/balance with the key as the apikey parameter.
Package neverbounce checks addresses with NeverBounce's v4.2 API (https://developers.neverbounce.com): GET /v4.2/account/info and GET /v4.2/single/check with the key as the key parameter.
Package neverbounce checks addresses with NeverBounce's v4.2 API (https://developers.neverbounce.com): GET /v4.2/account/info and GET /v4.2/single/check with the key as the key parameter.
Package zerobounce checks addresses with ZeroBounce's v2 API (https://www.zerobounce.net/docs/email-validation-api-quickstart/): GET /v2/getcredits, GET /v2/validate and POST /v2/validatebatch, on the default, United States or EU endpoint.
Package zerobounce checks addresses with ZeroBounce's v2 API (https://www.zerobounce.net/docs/email-validation-api-quickstart/): GET /v2/getcredits, GET /v2/validate and POST /v2/validatebatch, on the default, United States or EU endpoint.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL