Email verification in Go

package zapbounce

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"
)

type Client struct {
	key  string
	http *http.Client
}

func New(key string) *Client {
	return &Client{
		key: key,
		http: &http.Client{
			Timeout: 15 * time.Second, // the zero value is no timeout at all
			Transport: &http.Transport{
				MaxIdleConnsPerHost: 20,
				IdleConnTimeout:     90 * time.Second,
			},
		},
	}
}

type Result struct {
	Email    string `json:"email"`
	Verdict  string `json:"result"`
	Reason   string `json:"reason"`
	SMTPCode string `json:"smtp_code"`
	Billed   bool   `json:"billed"`
}

func (c *Client) Verify(ctx context.Context, email string) (*Result, error) {
	body, _ := json.Marshal(map[string]string{"email": email})

	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
		"https://api.zapbounce.com/v1/verify", bytes.NewReader(body))
	if err != nil {
		return nil, fmt.Errorf("build request: %w", err)
	}
	req.Header.Set("Authorization", "Bearer "+c.key)
	req.Header.Set("Content-Type", "application/json")

	res, err := c.http.Do(req)
	if err != nil {
		return nil, fmt.Errorf("verify %s: %w", email, err)
	}
	defer res.Body.Close() // leak this and connections are never reused

	if res.StatusCode != http.StatusOK {
		return nil, parseAPIError(res)
	}

	var out Result
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		return nil, fmt.Errorf("decode: %w", err)
	}
	return &out, nil
}

// Single verifications in parallel, bounded. Unbounded goroutines against one
// host is how you rate-limit yourself and end up with a page of 429s.
func (c *Client) VerifyMany(ctx context.Context, emails []string, workers int) []Outcome {
	jobs := make(chan string)
	out := make(chan Outcome, len(emails))

	var wg sync.WaitGroup
	for i := 0; i < workers; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for email := range jobs {
				r, err := c.Verify(ctx, email)
				out <- Outcome{Email: email, Result: r, Err: err}
			}
		}()
	}

	go func() {
		defer close(jobs)
		for _, e := range emails {
			select {
			case jobs <- e:
			case <-ctx.Done():
				return
			}
		}
	}()

	wg.Wait()
	close(out)

	results := make([]Outcome, 0, len(emails))
	for o := range out {
		results = append(results, o)
	}
	return results
}

// For a real list, submit a batch instead and let the server pace the probes.
func (c *Client) SubmitBatch(ctx context.Context, name string, emails []string) (string, error) {
	var resp struct {
		BatchID string `json:"batch_id"`
	}
	err := c.post(ctx, "/v1/batches", map[string]any{"name": name, "emails": emails}, &resp)
	return resp.BatchID, err
}

type APIError struct {
	Status    int
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
}

func (e *APIError) Error() string {
	return fmt.Sprintf("zapbounce: %s (%s, request_id=%s)", e.Message, e.Code, e.RequestID)
}

// Retryable reports whether another attempt could succeed. A 402 never will.
func (e *APIError) Retryable() bool {
	return e.Status == http.StatusTooManyRequests || e.Status >= 500
}

func (c *Client) VerifyWithRetry(ctx context.Context, email string) (*Result, error) {
	var last error
	for attempt := 0; attempt < 5; attempt++ {
		r, err := c.Verify(ctx, email)
		if err == nil {
			return r, nil
		}
		last = err

		var apiErr *APIError
		if errors.As(err, &apiErr) && !apiErr.Retryable() {
			return nil, err // insufficient_credits, malformed_email: stop here
		}

		backoff := time.Duration(1<<attempt) * 500 * time.Millisecond
		select {
		case <-time.After(backoff + jitter()):
		case <-ctx.Done():
			return nil, ctx.Err()
		}
	}
	return nil, fmt.Errorf("gave up after 5 attempts: %w", last)
}