Go SDK

The Orbit Go SDK wraps the platform’s core API resources — messaging (SMS, WhatsApp, email), voice, contacts, campaigns, verify (OTP), and webhook signature verification — with typed methods. It requires Go 1.22+ and is safe for concurrent use across goroutines.

Pre-publish — source-only. This SDK is not yet mirrored to the public Go module repository — go get github.com/devotel/orbit-go returns 404 today. Until first publish, vendor the source from the monorepo (packages/sdk-go/) or call the REST API directly. See Go: core-scope, not full parity on the SDK index for exactly what is and isn’t wrapped, and the low-level client.Request(ctx, method, path, ...) escape hatch for uncovered routes (worked example below).

Installation

go get github.com/devotel/orbit-go/orbit@latest

Client initialization

The client reads the key straight from your environment — there is no from_env helper in Go; use os.Getenv:

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/devotel/orbit-go/orbit"
)

func main() {
    client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
    if err != nil {
        panic(err)
    }
    _ = client
    _ = context.Background()
    fmt.Println("ready")
}

Tune the transport with functional options:

client, err := orbit.NewClient(
    "dv_live_sk_...",
    orbit.WithBaseURL("https://api.orbit.devotel.io/api/v1"),
    orbit.WithHTTPClient(myCustomHTTP),    // e.g. instrumented http.Client
    orbit.WithMaxRetries(5),
    orbit.WithInitialBackoff(500 * time.Millisecond),
)

Quickstart: send your first SMS

A runnable end-to-end — the key comes from ORBIT_API_KEY, never from source. Copy it into main.go and run it with go run .:

client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
if err != nil {
    log.Fatal(err)
}

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Hello from Orbit!",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("message id:", msg.Data.ID)       // msg_abc123
fmt.Println("status:", msg.Data.Status)       // "queued" — watch it reach "delivered"
fmt.Println("status URL:", "/api/v1/messages/"+msg.Data.ID)

Set ORBIT_API_KEY to a sandbox key prefixed dv_test_sk_ first — sandbox sends are simulated, free, and never reach a carrier. Swap in your live key (dv_live_sk_...) when you’re ready to send for real; the code does not change. The response shape above comes from the Messages API reference — its language tabs include this exact call.

Messaging

msg, err := client.Messages().SendSMS(context.Background(), orbit.SendSMSInput{
    To:   "+14155552671",
    Body: "Hello from Orbit!",
})
if err != nil {
    panic(err)
}
fmt.Println("queued:", msg.Data.ID)

client.Messages() also exposes SendWhatsApp, SendEmail, and Get (fetch a message by id).

Voice

call, err := client.Voice().Create(context.Background(), orbit.CreateVoiceCallInput{
    To: "+14155552671",
})
if err != nil {
    panic(err)
}

_ = call.Data.ID

client.Voice() also exposes Get, List, and Hangup(callID) — place a call, poll its status, then hang up. All outbound calls route through the Orbit API; the SDK never selects a carrier.

Second example: verify OTP

The send-and-check round trip is the most common first integration on the platform. Two calls — the key is still just ORBIT_API_KEY passed to orbit.NewClient:

// 1. Send an OTP (channel: sms | whatsapp | email).
sent, err := client.Verify().Send(context.Background(), "+14155552671", "sms")
if err != nil {
    log.Fatal(err)
}

// 2. Check the code the user typed in, against the verification id Send returned.
check, err := client.Verify().Check(context.Background(), sent.Data.ID, "482901")
if err != nil {
    log.Fatal(err)
}

fmt.Println("valid:", check.Data.Valid)      // true
fmt.Println("status:", check.Data.Status)    // "approved"

A wrongly-typed or expired code reports check.Data.Valid == false — it never errors for a bad guess (only for transport/auth failures), so branch on the flag. The Verify API reference covers the full contract, and Starter examples includes a complete OTP sign-in starter repo (orbit-otp-nextjs).

Verify (OTP)

sent, err := client.Verify().Send(context.Background(), "+14155552671", "sms")
if err != nil {
    panic(err)
}

check, err := client.Verify().Check(context.Background(), sent.Data.ID, "123456")
_ = check

client.Verify() also exposes Resend and GetDetail.

Contacts

contact, err := client.Contacts().Create(context.Background(), orbit.ContactCreateInput{
    Phone:     "+14155552671",
    FirstName: "Ada",
})
if err != nil {
    panic(err)
}
_ = contact

client.Contacts() also exposes List, Get, Update, and Delete.

Campaigns

campaign, err := client.Campaigns().Create(context.Background(), orbit.CampaignCreateInput{
    Name:    "Launch",
    Channel: "sms",
})
if err != nil {
    panic(err)
}

_, err = client.Campaigns().Send(context.Background(), campaign.Data.ID)

client.Campaigns() also exposes List, Get, Update, and Delete.

Paginate a list

List endpoints are cursor-paginated — read meta.pagination.cursor and meta.pagination.has_more off each response and pass the cursor back as a query parameter until has_more is false. Page through SMS messages with the escape hatch:

query := url.Values{"channel": {"sms"}, "limit": {"100"}}
total := 0

for {
    var page map[string]any
    if err := client.Request(context.Background(), "GET", "/messages", query, nil, &page, ""); err != nil {
        log.Fatal(err)
    }

    data := page["data"].([]any)
    total += len(data)

    pagination := page["meta"].(map[string]any)["pagination"].(map[string]any)
    if !pagination["has_more"].(bool) {
        break
    }
    query.Set("cursor", pagination["cursor"].(string))
}

fmt.Printf("Fetched %d messages\n", total)

The full pagination model (cursor vs. offset endpoints, page-size caps, and why cursors are not bookmarkable) is in the Pagination guide.

Error handling

All Orbit-originated errors are *orbit.Error. Inspect them with the helper predicates:

Predicate	Matches
`orbit.IsAuthentication(err)`	401/403 — rotate the API key
`orbit.IsRateLimit(err)`	429 — back off; `err.(*orbit.Error).RetryAfter` is set when the API provides it
`orbit.IsServerError(err)`	5xx — Orbit-side failure, also persistent network errors (`Kind == orbit.KindServer`, `Code == "network_error"`)

resp, err := client.Messages().SendSMS(ctx, in)
switch {
case orbit.IsRateLimit(err):
    // back off; err.(*orbit.Error).RetryAfter is set when the API provides it
case orbit.IsAuthentication(err):
    // rotate the API key
case orbit.IsServerError(err):
    // 5xx — Orbit-side failure
case err != nil:
    // 4xx — caller error
}
_ = resp

Every non-GET request automatically carries an Idempotency-Key header (UUID v4); override it per call via orbit.SendSMSInput{ ..., IdempotencyKey: "job-7a3b9d-attempt-1" } when retrying from your own queue.

Covered route missing? Use the escape hatch

The typed resources wrap 8 core resources; the rest of the API — contact segments, event sinks, frequency caps, and everything else listed as out of scope on the SDK index — is reachable through client.Request(ctx, method, path, ...). It unmarshals the raw JSON body into whatever out you pass (a map[string]any when you have no typed struct). Fetch a segment by id:

var segment map[string]any
err := client.Request(context.Background(), "GET", "/contacts/segments/seg_01hxyz", nil, nil, &segment, "")
if err != nil {
    panic(err)
}
fmt.Println(segment["data"].(map[string]any)["name"])

The escape hatch carries the same auth, retry, and error model as the typed resources — treat it as a first-class client, not a fallback http.Client.

Webhook signature verification

event, err := orbit.VerifyWebhook(
    requestBody,
    request.Header.Get("X-Orbit-Signature"),
    os.Getenv("ORBIT_WEBHOOK_SECRET"),
    0,            // tolerance — 0 = use default 5 minutes
    time.Time{},  // now — zero value = time.Now()
)
if err != nil {
    // Forgery attempt — drop, do NOT 200.
    w.WriteHeader(400)
    return
}
// event is a map[string]any — type-assert event["type"], etc.

SDKs

Go SDK: Orbit quickstart for Go

Go SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification

​Go SDK

​Installation

​Client initialization

​Quickstart: send your first SMS

​Messaging

​Voice

​Second example: verify OTP

​Verify (OTP)

​Contacts

​Campaigns

​Paginate a list

​Error handling

​Covered route missing? Use the escape hatch

​Webhook signature verification

Go SDK

Installation

Client initialization

Quickstart: send your first SMS

Messaging

Voice

Second example: verify OTP

Verify (OTP)

Contacts

Campaigns

Paginate a list

Error handling

Covered route missing? Use the escape hatch

Webhook signature verification