> ## Documentation Index
> Fetch the complete documentation index at: https://sendmux.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Go SDK

> Install and configure the Qubrics Go module.

Use the Go SDK when your application needs importable clients for the Sending, Mailbox, or Management API.

> [!NOTE]
>
> For API-key authentication, Sending clients accept a send-capable `smx_mbx_` key or owner-approved Sending-resource `smx_agent_` token. Mailbox clients accept
> `smx_mbx_` keys or scoped `smx_agent_` tokens. Management API-key clients require
> team-scoped `smx_root_` keys.

## Requirements

* Go 1.23 or newer.
* An API key or [REST OAuth grant](https://sendmux.ai/docs/developer-tools/oauth.md) for the surface you are calling.

## Install

The Go SDK is one module with surface subpackages.

```bash theme={null}
go get sendmux.ai/go/v3@latest
```

## OAuth access tokens

Use `NewWithAccessToken` for a bare token or `NewWithTokenProvider` for a function that receives the request context.

```go theme={null}
package example

import (
    "context"
    "os"
    "sendmux.ai/go/v3/mailbox"
)

func oauthClient() (*mailbox.Client, error) {
    return mailbox.NewWithTokenProvider(func(ctx context.Context) (string, error) {
        return os.Getenv("QUBRICS_ACCESS_TOKEN"), nil
    })
}
```

The provider runs before each request. Your application owns secure token storage, expiry checks, and refresh coordination; see [OAuth for REST APIs](https://sendmux.ai/docs/developer-tools/oauth.md#refresh-and-disconnect). The same token option is available for Sending and Management clients.

## Create a client

Import the surface package directly.

```go Sending theme={null}
package main

import (
	"log"
	"os"

	"sendmux.ai/go/v3/sending"
)

func main() {
	client, err := sending.New(os.Getenv("QUBRICS_MAILBOX_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	_ = client
}
```

```go Mailbox theme={null}
package main

import (
	"log"
	"os"

	"sendmux.ai/go/v3/mailbox"
)

func main() {
	client, err := mailbox.New(os.Getenv("QUBRICS_MAILBOX_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	_ = client
}
```

```go Management theme={null}
package main

import (
	"log"
	"os"

	"sendmux.ai/go/v3/management"
)

func main() {
	client, err := management.New(os.Getenv("QUBRICS_ROOT_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}

	_ = client
}
```

## Choose a surface

| Surface | Import path | Factory | API key |
| - | - | - | - |
| Sending | `sendmux.ai/go/v3/sending` | `sending.New` | `smx_mbx_` or owner-approved `smx_agent_` with `email.send` |
| Mailbox | `sendmux.ai/go/v3/mailbox` | `mailbox.New` | `smx_mbx_` or scoped `smx_agent_` |
| Management | `sendmux.ai/go/v3/management` | `management.New` | `smx_root_` |

> [!NOTE]
>
> Durable `smx_agent_` tokens are mailbox-compatible and include `mailbox.read`
> and `email.receive`, not `email.send`. After owner acceptance and approval,
> exchange the durable token for a one-hour Sending-resource token before sending.

Sending uses `https://smtp.sendmux.ai/api/v1` by default. Mailbox and Management use `https://app.sendmux.ai/api/v1`.

## Shared API behaviour

Surface packages validate API key prefixes, attach bearer auth, and wrap an HTTP client with retry behaviour.

### Pagination

List responses use cursor pagination with `pagination.has_more` and `pagination.next_cursor`. The `core` package exports `IterateCursor()` for cursor iteration when you wrap a page-fetching function.

### Retries and rate limits

Surface clients use `core.NewHTTPClient()` by default. It retries safe requests and requests that carry `Idempotency-Key`, then honours `Retry-After` and `X-RateLimit-Reset` response headers.

Pass `WithRetryOptions(core.RetryOptions{...})` into a surface factory to change attempts and backoff.

### Idempotency and ETags

Use surface header helpers when a generated operation accepts optional header values.

```go theme={null}
idempotencyKey := sending.IdempotencyKey("order-123")
ifMatch := sending.IfMatch(etag)
ifNoneMatch := sending.IfNoneMatch(etag)

_, _, _ = idempotencyKey, ifMatch, ifNoneMatch
```

Use `Idempotency-Key` for retry-safe mutating requests. Use `If-Match` and `If-None-Match` with single-resource endpoints that support ETags.

### Errors

The `core` package defines `core.APIError`. Surface packages expose `APIErrorFromResponse()` to map generated error responses into the typed API error shape.

Keep the request ID from the API response when contacting support.

## Next steps

> [card] [SDK overview](https://sendmux.ai/docs/developer-tools/sdks)
>
> Choose the right package family and API surface.

> [card] [Versioning and support](https://sendmux.ai/docs/developer-tools/sdks/versioning-support.md)
>
> Check compatibility, support, and upgrade guidance.

> [card] [Management API](https://sendmux.ai/docs/api/introduction.md)
>
> Review the Management API contract used by `sendmux.ai/go/v3/management`.

> [card] [API keys](https://sendmux.ai/docs/account/api-keys.md)
>
> Create and scope the credentials used by SDK clients.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.