mailcheckr

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 14 Imported by: 0

README

MailCheckr for Go

Server-side Go client for the MailCheckr API. It uses only the Go standard library.

Install

go get github.com/dotmarn/mailcheckr-go

Set MAILCHECKR_API_KEY on your server and keep it out of client-side code.

Verify an email

package main

import (
    "context"
    "log"
    "os"

    mailcheckr "github.com/dotmarn/mailcheckr-go"
)

func main() {
    client, err := mailcheckr.NewClient(os.Getenv("MAILCHECKR_API_KEY"))
    if err != nil { log.Fatal(err) }

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

    if result.IsPending() {
        // Save result.ID and poll later, or handle a webhook.
        result, err = client.Find(context.Background(), result.ID)
        if err != nil { log.Fatal(err) }
    }

    if result.IsDeliverable() {
        log.Println("Address is deliverable")
    }
}

Use a stable idempotency key for each verification, and reuse it when retrying the same email. Reusing a key with a different email receives HTTP 409. Verify accepts both HTTP 200 completed and HTTP 202 pending results. Pending states are queued, processing, and retry_scheduled; completed statuses are deliverable, undeliverable, risky, and unknown. Only a completed deliverable result passes IsDeliverable().

NewClient accepts WithBaseURL and WithHTTPClient options. The default base URL is https://mailcheckr.app/api/v1; the default HTTP timeout is 30 seconds. Verification.Raw contains the complete API data object, including fields added later. API failures return *mailcheckr.APIError with StatusCode and Response; network and timeout failures return the underlying Go error.

Verify webhooks

Verify the exact raw body before parsing JSON or applying the event:

verifier := mailcheckr.NewWebhookVerifier(os.Getenv("MAILCHECKR_WEBHOOK_SECRET"))

http.HandleFunc("/webhooks/mailcheckr", func(w http.ResponseWriter, r *http.Request) {
    body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
    if err != nil || !verifier.Verify(body, r.Header) {
        http.Error(w, "invalid webhook", http.StatusUnauthorized)
        return
    }
    // Parse body, then persist and deduplicate the event ID before applying effects.
    w.WriteHeader(http.StatusNoContent)
})

The verifier checks the X-MailCheckr-Signature HMAC SHA-256 over X-MailCheckr-Timestamp + "." + raw body and rejects timestamps outside a five-minute window. Pass a positive time.Duration to NewWebhookVerifier(secret, tolerance) to customize the window. Valid deliveries can be retried, so deduplicate event IDs in persistent storage.

Development

go test ./...
go vet ./...

See CONTRIBUTING.md and SECURITY.md.

License

MIT

Documentation

Overview

Package mailcheckr provides a server-side client for the MailCheckr API.

Index

Constants

View Source
const DefaultBaseURL = "https://mailcheckr.app/api/v1"

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Response   map[string]any
}

APIError is a non-2xx response. Response holds the decoded JSON error body when available.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client calls the MailCheckr verification API.

func NewClient

func NewClient(apiKey string, options ...Option) (*Client, error)

NewClient creates a client using a server-side API key.

func (*Client) Find

func (c *Client) Find(ctx context.Context, id string) (*Verification, error)

Find retrieves the latest state of a verification by ID.

func (*Client) Verify

func (c *Client) Verify(ctx context.Context, email, idempotencyKey string) (*Verification, error)

Verify starts or reuses a verification. Reuse the same idempotency key when retrying the same email.

type Option

type Option func(*Client) error

Option configures a Client.

func WithBaseURL

func WithBaseURL(raw string) Option

WithBaseURL sets the API base URL, primarily for private installations or tests.

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient supplies an HTTP client. Its timeout and transport are respected.

type Verification

type Verification struct {
	ID          string          `json:"id"`
	Email       string          `json:"email"`
	State       string          `json:"state"`
	Status      *string         `json:"status"`
	Reason      *string         `json:"reason"`
	Checks      json.RawMessage `json:"checks"`
	Attempts    int             `json:"attempts"`
	CreatedAt   *time.Time      `json:"created_at"`
	CompletedAt *time.Time      `json:"completed_at"`
	Raw         json.RawMessage `json:"-"`
}

Verification is a verification result. Raw contains the full API data object.

func (Verification) IsCompleted

func (v Verification) IsCompleted() bool

func (Verification) IsDeliverable

func (v Verification) IsDeliverable() bool

func (Verification) IsFailed

func (v Verification) IsFailed() bool

func (Verification) IsPending

func (v Verification) IsPending() bool

func (Verification) IsRisky

func (v Verification) IsRisky() bool

func (Verification) IsUndeliverable

func (v Verification) IsUndeliverable() bool

func (Verification) IsUnknown

func (v Verification) IsUnknown() bool

type WebhookVerifier

type WebhookVerifier struct {
	// contains filtered or unexported fields
}

WebhookVerifier validates a signature against the exact raw request body.

func NewWebhookVerifier

func NewWebhookVerifier(secret string, tolerance ...time.Duration) *WebhookVerifier

NewWebhookVerifier uses a five-minute timestamp tolerance by default. A supplied tolerance must be positive.

func (*WebhookVerifier) Verify

func (w *WebhookVerifier) Verify(body []byte, headers http.Header) bool

Verify checks the MailCheckr headers and exact raw body bytes.

func (*WebhookVerifier) VerifyPayload

func (w *WebhookVerifier) VerifyPayload(body []byte, timestamp, signature string) bool

VerifyPayload checks a timestamped v1 HMAC-SHA256 signature.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL