> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Go SDK

## Install

```bash
go get github.com/usgm/usgm-go
```

Requires Go 1.21+.

## Initialize

```go
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`.

```go
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"`:

```go
_, 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
}
```

> **Note**
>
> Transient `429` and `5xx` responses are retried automatically with exponential backoff. See
> [Errors](/guides/core-concepts/errors) for the full problem+json contract.