Go SDK

A fully-typed, idiomatic client for Go.

Install

$go get github.com/usgm/usgm-go

Requires Go 1.21+.

Initialize

1package main
2
3import (
4 "os"
5
6 usgmclient "github.com/usgm/usgm-go/client"
7 "github.com/usgm/usgm-go/option"
8)
9
10func main() {
11 client := usgmclient.NewClient(
12 option.WithToken(os.Getenv("USGM_API_KEY")), // never hard-code the key
13 )
14 _ = client
15}

Usage

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

1ctx := context.Background()
2
3// Your account profile
4account, err := client.Account.Get(ctx)
5if err != nil {
6 return err
7}
8fmt.Println(account.Email)
9
10// List mail, one page at a time (cursor pagination)
11var cursor *string
12for {
13 page, err := client.Mails.List(ctx, &usgm.MailsListRequest{Cursor: cursor})
14 if err != nil {
15 return err
16 }
17 for _, mail := range page.Data {
18 fmt.Println(mail.ID, mail.MailStatus)
19 }
20 if page.NextCursor == nil {
21 break
22 }
23 cursor = page.NextCursor
24}
25
26// Fetch one item
27mail, err := client.Mails.Get(ctx, &usgm.MailsGetRequest{ID: "80421"})
28
29// Create a folder
30folder, 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":

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

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