Go

Check an email from your Go signup handler before account creation. Keep the API key in server configuration and share one client across goroutines to reuse its HTTP transport.

Availability

Install the published Go SDK. Go 1.23 or newer is required.

go get github.com/IrondomeDev/sdks/go@v0.2.0

Create and reuse a client

package main

import (
	"context"
	"errors"
	"log"
	"os"
	"time"

	irondome "github.com/IrondomeDev/sdks/go"
)

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	client, err := irondome.New(os.Getenv("IRONDOME_API_KEY"), irondome.Options{})
	if err != nil {
		return errors.New("invalid IronDome configuration")
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
	defer cancel()
	result, err := client.Check(ctx, "person@example.com")
	if err != nil {
		var apiErr *irondome.Error
		if errors.As(err, &apiErr) && apiErr.Kind == irondome.API {
			log.Printf("check failed: status=%d code=%s request_id=%s", apiErr.StatusCode, apiErr.Code, apiErr.RequestID)
		}
		return errors.New("IronDome check failed")
	}
	log.Printf("disposable=%t reason=%s", result.Disposable, result.Reason)
	return nil
}

irondome.Options{} uses https://api.irondome.dev. Options.BaseURL is available for a trusted staging or local test origin. In a server, create the client at startup, pass each handler's context to Check, and call Close after requests have drained at final shutdown.

Results and failures

Check returns a result with provider, validity, disposable classification, and reason. The valid field does not establish that a mailbox exists or can receive mail. Use errors.As with *irondome.Error to inspect error kind and safe API metadata; do not turn an error into a non-disposable result. A canceled or timed-out request may already have been processed.

Warmup(ctx) optionally sends a health request through the same pool. It does not check authorization. Use it ahead of independent work if useful, rather than before each check.

CheckBulk(ctx, emails) accepts 1–100 addresses and returns results in input order. Each valid address counts as one check. See the bulk API guide and performance guide.