Skip to navigation

Go SDK

A fully-typed, idiomatic client for Go.

Install

go get github.com/usgm/usgm-go

Requires Go 1.21+.

Initialize

package main
import (
"os"
usgmclient "github.com/usgm/usgm-go/client"
"github.com/usgm/usgm-go/option"
)
func main() {
client := usgmclient.NewClient(
option.WithToken(os.Getenv("USGM_API_KEY")), // never hard-code the key
)
_ = client
}

Usage

The snippets below assume the package imports usgm "github.com/usgm/usgm-go" for request/response types, plus context and fmt.

ctx := context.Background()
// Your account profile
account, err := client.Account.Get(ctx)
if err != nil {
return err
}
fmt.Println(account.Email)
// List mail, one page at a time (cursor pagination)
var cursor *string
for {
page, err := client.Mails.List(ctx, &usgm.MailsListRequest{Cursor: cursor})
if err != nil {
return err
}
for _, mail := range page.Data {
fmt.Println(mail.ID, mail.MailStatus)
}
if page.NextCursor == nil {
break
}
cursor = page.NextCursor
}
// Fetch one item
mail, err := client.Mails.Get(ctx, &usgm.MailsGetRequest{ID: "80421"})
// Create a folder
folder, err := client.Folders.Create(ctx, &usgm.CreateFolderDto{Name: "Taxes"})

Error handling

Structured errors are compatible with errors.As. Import "github.com/usgm/usgm-go/core":

_, err := client.Mails.Get(ctx, &usgm.MailsGetRequest{ID: "does-not-exist"})
if err != nil {
var apiErr *core.APIError
if errors.As(err, &apiErr) {
log.Printf("status %d", apiErr.StatusCode)
}
return err
}

Transient 429 and 5xx responses are retried automatically with exponential backoff. See Errors for the full problem+json contract.