Go SDK

Go email checker SDK. Install, configure, verify emails with Golang. Code examples included.

Das offizielle EmailVerify SDK für Go bietet idiomatische Go-Schnittstellen für die E-Mail-Verifizierung mit integrierter Parallelitätsunterstützung.

Installieren

go get github.com/emailverify/go-sdk

Schnellstart

package main

import (
    "context"
    "fmt"
    "os"

    emailverify "github.com/emailverify/go-sdk"
)

func main() {
    client := emailverify.NewClient(os.Getenv("EMAILVERIFY_API_KEY"))

    ctx := context.Background()
    result, err := client.Verify(ctx, "user@example.com")
    if err != nil {
        panic(err)
    }

    fmt.Printf("Status: %s\n", result.Status)
    fmt.Printf("Score: %.2f\n", result.Score)
}

Konfiguration

Client-Optionen

client := emailverify.NewClient(
    os.Getenv("EMAILVERIFY_API_KEY"),
    emailverify.WithTimeout(30*time.Second),
    emailverify.WithRetries(3),
    emailverify.WithBaseURL("https://api.emailverify.ai"),
)

Verfügbare Optionen

// Request-Timeout festlegen
emailverify.WithTimeout(30 * time.Second)

// Anzahl der Wiederholungsversuche festlegen
emailverify.WithRetries(3)

// Benutzerdefinierte Basis-URL festlegen
emailverify.WithBaseURL("https://custom-api.example.com")

// Benutzerdefinierten HTTP-Client festlegen
emailverify.WithHTTPClient(&http.Client{
    Timeout: 30 * time.Second,
})

Typen

Verifizierungsergebnis

type VerificationResult struct {
    Email  string        `json:"email"`
    Status string        `json:"status"` // "valid", "invalid", "unknown", "accept_all"
    Result ResultDetails `json:"result"`
    Score  float64       `json:"score"`
    Reason *string       `json:"reason"`
}

type ResultDetails struct {
    Deliverable *bool `json:"deliverable"`
    ValidFormat bool  `json:"valid_format"`
    ValidDomain bool  `json:"valid_domain"`
    ValidMX     bool  `json:"valid_mx"`
    Disposable  bool  `json:"disposable"`
    Role        bool  `json:"role"`
    Catchall    bool  `json:"catchall"`
    Free        bool  `json:"free"`
    SMTPValid   *bool `json:"smtp_valid"`
}

Massenauftrag

type BulkJob struct {
    ID          string    `json:"id"`
    Status      string    `json:"status"` // "pending", "processing", "completed", "failed"
    Total       int       `json:"total"`
    Processed   int       `json:"processed"`
    Valid       int       `json:"valid"`
    Invalid     int       `json:"invalid"`
    Unknown     int       `json:"unknown"`
    CreatedAt   time.Time `json:"created_at"`
    CompletedAt *time.Time `json:"completed_at"`
}

Einzelverifizierung

Grundlegende Verifizierung

ctx := context.Background()
result, err := client.Verify(ctx, "user@example.com")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Email: %s\n", result.Email)
fmt.Printf("Status: %s\n", result.Status)
fmt.Printf("Score: %.2f\n", result.Score)
fmt.Printf("Disposable: %v\n", result.Result.Disposable)

Mit Optionen

result, err := client.Verify(ctx, "user@example.com",
    emailverify.WithSMTPCheck(true),
    emailverify.WithVerifyTimeout(5*time.Second),
)

Context mit Timeout

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

result, err := client.Verify(ctx, "user@example.com")
if err != nil {
    if ctx.Err() == context.DeadlineExceeded {
        log.Println("Verifizierung hat Timeout überschritten")
    }
    log.Fatal(err)
}

Massenverifizierung

Auftrag einreichen

emails := []string{
    "user1@example.com",
    "user2@example.com",
    "user3@example.com",
}

job, err := client.VerifyBulk(ctx, emails)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Job-ID: %s\n", job.ID)

Status prüfen

status, err := client.GetBulkJobStatus(ctx, job.ID)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Status: %s\n", status.Status)
fmt.Printf("Fortschritt: %d/%d\n", status.Processed, status.Total)

Ergebnisse abrufen

results, err := client.GetBulkJobResults(ctx, job.ID)
if err != nil {
    log.Fatal(err)
}

for _, result := range results {
    fmt.Printf("%s: %s\n", result.Email, result.Status)
}

Mit Webhook

job, err := client.VerifyBulk(ctx, emails,
    emailverify.WithWebhookURL("https://your-domain.com/webhooks/emailverify"),
)

Gleichzeitige Verifizierung

Mit Goroutines

func verifyEmails(ctx context.Context, client *emailverify.Client, emails []string) []VerificationResult {
    results := make([]VerificationResult, len(emails))
    var wg sync.WaitGroup

    for i, email := range emails {
        wg.Add(1)
        go func(idx int, email string) {
            defer wg.Done()
            result, err := client.Verify(ctx, email)
            if err != nil {
                log.Printf("Fehler beim Verifizieren von %s: %v", email, err)
                return
            }
            results[idx] = *result
        }(i, email)
    }

    wg.Wait()
    return results
}

Mit Worker-Pool

func verifyWithWorkerPool(ctx context.Context, client *emailverify.Client, emails []string, workers int) <-chan *emailverify.VerificationResult {
    emailChan := make(chan string, len(emails))
    resultChan := make(chan *emailverify.VerificationResult, len(emails))

    // Worker starten
    var wg sync.WaitGroup
    for i := 0; i < workers; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            for email := range emailChan {
                result, err := client.Verify(ctx, email)
                if err != nil {
                    log.Printf("Fehler: %v", err)
                    continue
                }
                resultChan <- result
            }
        }()
    }

    // E-Mails senden
    go func() {
        for _, email := range emails {
            emailChan <- email
        }
        close(emailChan)
    }()

    // Ergebnisse schließen, wenn fertig
    go func() {
        wg.Wait()
        close(resultChan)
    }()

    return resultChan
}

// Verwendung
results := verifyWithWorkerPool(ctx, client, emails, 10)
for result := range results {
    fmt.Printf("%s: %s\n", result.Email, result.Status)
}

Mit errgroup

import "golang.org/x/sync/errgroup"

func verifyEmailsConcurrently(ctx context.Context, client *emailverify.Client, emails []string) ([]*emailverify.VerificationResult, error) {
    g, ctx := errgroup.WithContext(ctx)
    results := make([]*emailverify.VerificationResult, len(emails))

    for i, email := range emails {
        i, email := i, email // Loop-Variablen erfassen
        g.Go(func() error {
            result, err := client.Verify(ctx, email)
            if err != nil {
                return fmt.Errorf("verify %s: %w", email, err)
            }
            results[i] = result
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return nil, err
    }

    return results, nil
}

Fehlerbehandlung

Fehlertypen

import "github.com/emailverify/go-sdk/errors"

result, err := client.Verify(ctx, email)
if err != nil {
    switch e := err.(type) {
    case *errors.AuthenticationError:
        log.Fatal("Ungültiger API-Schlüssel")
    case *errors.RateLimitError:
        log.Printf("Rate-Limit erreicht. Wiederholen nach %v", e.RetryAfter)
    case *errors.ValidationError:
        log.Printf("Ungültige Eingabe: %s", e.Message)
    case *errors.APIError:
        log.Printf("API-Fehler: %s (Code: %s)", e.Message, e.Code)
    default:
        log.Printf("Unbekannter Fehler: %v", err)
    }
}

Benutzerdefinierter Fehlerbehandler

func verifyWithRetry(ctx context.Context, client *emailverify.Client, email string) (*emailverify.VerificationResult, error) {
    var lastErr error

    for attempt := 0; attempt < 3; attempt++ {
        result, err := client.Verify(ctx, email)
        if err == nil {
            return result, nil
        }

        lastErr = err

        // Prüfen, ob wiederholt werden soll
        if rateLimitErr, ok := err.(*errors.RateLimitError); ok {
            time.Sleep(rateLimitErr.RetryAfter)
            continue
        }

        // Validierungsfehler nicht wiederholen
        if _, ok := err.(*errors.ValidationError); ok {
            return nil, err
        }

        // Exponentieller Backoff für andere Fehler
        time.Sleep(time.Duration(attempt+1) * time.Second)
    }

    return nil, lastErr
}

Guthaben-Verwaltung

credits, err := client.GetCredits(ctx)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Verfügbar: %d\n", credits.Available)
fmt.Printf("Verbraucht: %d\n", credits.Used)
fmt.Printf("Gesamt: %d\n", credits.Total)

Framework-Integration

Gin

import "github.com/gin-gonic/gin"

func setupRouter(client *emailverify.Client) *gin.Engine {
    r := gin.Default()

    r.POST("/verify", func(c *gin.Context) {
        var req struct {
            Email string `json:"email" binding:"required,email"`
        }

        if err := c.ShouldBindJSON(&req); err != nil {
            c.JSON(400, gin.H{"error": err.Error()})
            return
        }

        result, err := client.Verify(c.Request.Context(), req.Email)
        if err != nil {
            c.JSON(500, gin.H{"error": "Verifizierung fehlgeschlagen"})
            return
        }

        c.JSON(200, result)
    })

    return r
}

Echo

import "github.com/labstack/echo/v4"

func setupRoutes(e *echo.Echo, client *emailverify.Client) {
    e.POST("/verify", func(c echo.Context) error {
        var req struct {
            Email string `json:"email"`
        }

        if err := c.Bind(&req); err != nil {
            return c.JSON(400, map[string]string{"error": "Ungültige Anfrage"})
        }

        result, err := client.Verify(c.Request().Context(), req.Email)
        if err != nil {
            return c.JSON(500, map[string]string{"error": "Verifizierung fehlgeschlagen"})
        }

        return c.JSON(200, result)
    })
}

Fiber

import "github.com/gofiber/fiber/v2"

func setupFiber(client *emailverify.Client) *fiber.App {
    app := fiber.New()

    app.Post("/verify", func(c *fiber.Ctx) error {
        var req struct {
            Email string `json:"email"`
        }

        if err := c.BodyParser(&req); err != nil {
            return c.Status(400).JSON(fiber.Map{"error": "Ungültige Anfrage"})
        }

        result, err := client.Verify(context.Background(), req.Email)
        if err != nil {
            return c.Status(500).JSON(fiber.Map{"error": "Verifizierung fehlgeschlagen"})
        }

        return c.JSON(result)
    })

    return app
}

Vollständiges Beispiel

E-Mail-Validierungsservice

package main

import (
    "context"
    "log"
    "os"

    emailverify "github.com/emailverify/go-sdk"
)

type ValidationResult struct {
    Valid   bool   `json:"valid"`
    Reason  string `json:"reason,omitempty"`
    Message string `json:"message,omitempty"`
    Score   float64 `json:"score,omitempty"`
}

type EmailValidator struct {
    client *emailverify.Client
}

func NewEmailValidator() *EmailValidator {
    return &EmailValidator{
        client: emailverify.NewClient(os.Getenv("EMAILVERIFY_API_KEY")),
    }
}

func (v *EmailValidator) ValidateForRegistration(ctx context.Context, email string) ValidationResult {
    result, err := v.client.Verify(ctx, email)
    if err != nil {
        return ValidationResult{
            Valid:   false,
            Reason:  "verification_error",
            Message: "E-Mail-Adresse konnte nicht verifiziert werden",
        }
    }

    // Ungültige E-Mails ablehnen
    if result.Status == "invalid" {
        return ValidationResult{
            Valid:   false,
            Reason:  "invalid_email",
            Message: "Diese E-Mail-Adresse ist ungültig",
        }
    }

    // Wegwerf-E-Mails ablehnen
    if result.Result.Disposable {
        return ValidationResult{
            Valid:   false,
            Reason:  "disposable",
            Message: "Bitte verwenden Sie eine permanente E-Mail-Adresse",
        }
    }

    // Warnung bei rollenbasierten E-Mails, aber zulassen
    if result.Result.Role {
        return ValidationResult{
            Valid:   true,
            Reason:  "role_based",
            Message: "Die Verwendung einer persönlichen E-Mail wird empfohlen",
            Score:   result.Score,
        }
    }

    return ValidationResult{
        Valid: true,
        Score: result.Score,
    }
}

func main() {
    validator := NewEmailValidator()

    ctx := context.Background()
    result := validator.ValidateForRegistration(ctx, "user@example.com")

    if !result.Valid {
        log.Printf("Ungültig: %s - %s", result.Reason, result.Message)
        return
    }

    log.Printf("Gültige E-Mail mit Score: %.2f", result.Score)
}

Best Practices

1. Immer Context verwenden

// Timeout für alle Operationen festlegen
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.Verify(ctx, email)

2. Nil-Zeiger behandeln

if result.Result.Deliverable != nil {
    fmt.Printf("Zustellbar: %v\n", *result.Result.Deliverable)
}

3. Connection-Pooling verwenden

// Client über Anfragen hinweg wiederverwenden
var client *emailverify.Client

func init() {
    client = emailverify.NewClient(os.Getenv("EMAILVERIFY_API_KEY"))
}