SDK QUICKSTART

Verify emails from Go.

Context-aware client, zero third-party dependencies, works on Go 1.21+.

1. Install

Grab a free API key at tooltrace.io/signup. The free plan includes 1,000 verifications per month.

Installbash
go get github.com/tooltrace/tooltrace-go

2. Quickstart

Set TOOLTRACE_KEY in your environment, then verify a single address.

Verify a single addressgo
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/tooltrace/tooltrace-go"
)

func main() {
    client := tooltrace.NewClient(os.Getenv("TOOLTRACE_KEY"))

    result, err := client.VerifyEmail(context.Background(), tooltrace.VerifyEmailParams{
        Email: "[email protected]",
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Status)      // "valid"
    fmt.Println(result.Score)       // 97
    fmt.Println(result.Checks.MX)   // true
    fmt.Println(result.Reasons)     // ["mailbox_confirmed", "mx_present"]

    if result.Status == tooltrace.StatusValid && result.Score >= 80 {
        acceptLead(result.Email)
    } else {
        flagForReview(result)
    }
}

3. Bulk verify

Submit up to 50,000 addresses in one job. Duplicates on the normalised form are deduped server-side and never charged. A signed webhook fires on completion.

Bulk verify a slicego
job, err := client.BulkVerify(ctx, tooltrace.BulkVerifyParams{
    Emails:     emails,                                   // up to 50,000 addresses
    WebhookURL: "https://your.app/hooks/tooltrace",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(job.JobID)              // "job_01HM8K2TGQX5RTF9W6"
fmt.Println(job.UniqueCount)        // dedupe-free billing
fmt.Println(job.EstimatedCredits)

// Stream results as they finish:
rows, err := client.JobResults(ctx, job.JobID)
if err != nil {
    log.Fatal(err)
}
for row := range rows {
    writer.Write([]string{row.Email, string(row.Status), fmt.Sprint(row.Score)})
}

4. Advanced

Patterns for production use: idempotency, retries, and typed errors.

Context, retries, and signed webhooksgo
client := tooltrace.NewClient(
    os.Getenv("TOOLTRACE_KEY"),
    tooltrace.WithMaxRetries(3),             // Retry-After honoured automatically
    tooltrace.WithTimeout(15*time.Second),
)

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

result, err := client.VerifyEmail(ctx, tooltrace.VerifyEmailParams{
    Email:          "[email protected]",
    IdempotencyKey: requestID,               // safe to retry within 24h
})

// Verify signed webhooks in your handler:
http.HandleFunc("/hooks/tooltrace", func(w http.ResponseWriter, r *http.Request) {
    body, _ := io.ReadAll(r.Body)
    sig := r.Header.Get("X-ToolTrace-Signature")
    if !tooltrace.VerifyWebhookSignature(body, sig, os.Getenv("TOOLTRACE_WEBHOOK_SECRET")) {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }
    // ... process the event
})

What you get

  • Context-aware: every call accepts a context.Context for cancellation and deadlines
  • Zero third-party dependencies, uses only the standard library
  • Typed responses, no map[string]interface{} to crawl through
  • Automatic Retry-After handling on 429
  • Signed webhook verification helper included

External links