Docs

Verify emails in Gin

Use a handler that forwards the address and returns only what the browser needs. The API key stays on your server; the browser only talks to your own endpoint.

Before you start

Create an API key under Settings → API keys and keep it in an environment variable named VALIDREACH_API_KEY on your server. Never ship it in browser or mobile code.

Example

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"

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

func main() {
	r := gin.Default()
	r.POST("/verify", func(c *gin.Context) {
		var in struct {
			Email string `json:"email"`
		}
		if err := c.BindJSON(&in); err != nil {
			return
		}
		payload, _ := json.Marshal(map[string]string{"email": in.Email})
		req, _ := http.NewRequest("POST", "https://validreach.dev/api/v1/verify/single", bytes.NewReader(payload))
		req.Header.Set("Authorization", "Bearer "+os.Getenv("VALIDREACH_API_KEY"))
		req.Header.Set("Content-Type", "application/json")
		res, err := http.DefaultClient.Do(req)
		if err != nil {
			c.JSON(http.StatusOK, gin.H{"status": "unknown"})
			return
		}
		defer res.Body.Close()
		var body struct {
			Success bool           `json:"success"`
			Data    map[string]any `json:"data"`
		}
		if json.NewDecoder(res.Body).Decode(&body) != nil || !body.Success {
			c.JSON(http.StatusOK, gin.H{"status": "unknown"})
			return
		}
		c.JSON(http.StatusOK, gin.H{
			"status":         body.Data["status"],
			"is_deliverable": body.Data["is_deliverable"],
		})
	})
	r.Run()
}

Handle the result

Branch on data.status. Treat invalid and disposable as rejections, retry unknown later when retryable is true (unknown is not billed), and decide on catchall, risky and role by your own policy. HTTP 402 means out of credits and 429 means rate limited.