Go SDK Overview

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.

Coverage. The Go SDK does not generate invitations, URL verification, sub-accounts, balance, account, functions and 10DLC yet, and no SDK generates voice calls. Those endpoints are still reachable: use the CLI or the REST API. See the coverage table.

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("+14155551234"),
		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("+14155551234"),
		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("+14155551234"),
	Text:        zavudev.String("Hello!"),
	Channel:     zavudev.String("sms"),
	MessageType: zavudev.String("text"),
}

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

​Installation

​Requirements

​Quick Start

​Configuration

​Initialize the Client

​Environment Variables

​Accessing Response Headers

​Error Handling

​Error Types

​Retries

​Type Safety

Installation

Requirements

Quick Start

Configuration

Initialize the Client

Environment Variables

Accessing Response Headers

Error Handling

Error Types

Retries

Type Safety