Go SDK Overview

Official Zavu SDK for Go. Send SMS, WhatsApp, Email and Voice messages with idiomatic Go errors, context support, retries and idempotency.

Server-side only — This SDK is designed for server-side environments (Go servers, CLI tools). Never use it in browser/frontend code as this exposes your API key. See Frontend Integration for the proxy pattern.

The official Zavu SDK for Go provides a strongly-typed, idiomatic Go interface to the Zavu API.

Installation

go get github.com/zavudev/sdk-go

Requirements

• Go 1.21 or higher

Quick Start

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

func main() {
	client := zavudev.NewClient(
		option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")),
	)

	result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
		To:   zavudev.String("[phone]"),
		Text: zavudev.String("Hello from Zavu!"),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println("Message sent:", result.Message.ID)
}

Configuration

Initialize the Client

import (
	"github.com/zavudev/sdk-go"
	"github.com/zavudev/sdk-go/option"
)

// Basic initialization
client := zavudev.NewClient(
	option.WithAPIKey(os.Getenv("ZAVUDEV_API_KEY")),
)

// With custom base URL
client := zavudev.NewClient(
	option.WithAPIKey("zv_live_xxx"),
	option.WithBaseURL("https://api.zavu.dev"),
)

Environment Variables

The SDK reads ZAVUDEV_API_KEY automatically if no key is provided:

// Will use ZAVUDEV_API_KEY environment variable
client := zavudev.NewClient()

Accessing Response Headers

Use option.WithResponseInto() to access the full HTTP response including headers (useful for rate limiting):

import "net/http"

var response *http.Response

result, err := client.Messages.Send(
	context.TODO(),
	zavudev.MessageSendParams{
		To:   zavudev.String("[phone]"),
		Text: zavudev.String("Hello!"),
	},
	option.WithResponseInto(&response),
)
if err != nil {
	panic(err)
}

remaining := response.Header.Get("X-RateLimit-Remaining")
fmt.Println("Remaining requests:", remaining)
fmt.Println("Message ID:", result.Message.ID)

Error Handling

import (
	"errors"
	"fmt"

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

result, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
	To:   zavudev.String("invalid-number"),
	Text: zavudev.String("Hello"),
})
if err != nil {
	var apiErr *zavudev.APIError
	if errors.As(err, &apiErr) {
		fmt.Println("Status:", apiErr.StatusCode)
		fmt.Println("Message:", apiErr.Message)
	} else {
		fmt.Println("Error:", err)
	}
	return
}

Error Types

Error Code	Description
400	Invalid request parameters
401	Invalid or missing API key
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded

Retries

The SDK supports automatic retries with configurable backoff:

client := zavudev.NewClient(
	option.WithAPIKey("zv_live_xxx"),
	option.WithMaxRetries(3),
)

Type Safety

The SDK provides strongly-typed request and response types:

params := zavudev.MessageSendParams{
	To:          zavudev.String("[phone]"),
	Text:        zavudev.String("Hello!"),
	Channel:     zavudev.String("sms"),
	MessageType: zavudev.String("text"),
}

result, err := client.Messages.Send(context.TODO(), params)