Go SDK

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

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 clients require team-scoped smx_root_ keys.

Requirements

Go 1.23 or newer.
A Sendmux API key for the surface you are calling.

Install

The Go SDK is one module with surface subpackages.

go get sendmux.ai/go@v1.0.0

Create a client

Import the surface package directly.

package main

import (
	"log"
	"os"

	"sendmux.ai/go/sending"
)

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

	_ = client
}

package main

import (
	"log"
	"os"

	"sendmux.ai/go/mailbox"
)

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

	_ = client
}

package main

import (
	"log"
	"os"

	"sendmux.ai/go/management"
)

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

	_ = client
}

Choose a surface

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

Pre-claim smx_agent_ tokens are mailbox-compatible only. Owner-approved Sending-resource smx_agent_ tokens can send. Pre-claim self-registered agent tokens include mailbox.read and email.receive, not email.send.

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.

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

SDK overview

Choose the right package family and API surface.

Versioning and support

Check compatibility, support, and upgrade guidance.

Management API

Review the Management API contract used by sendmux.ai/go/management.

API keys

Create and scope the credentials used by SDK clients.

Getting started

SDKs and CLI

Use cases

Integrations

AI integrations

Teams and access

Sending

Receiving

Monitoring

Webhooks

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Retries and rate limits

Idempotency and ETags

Errors

Next steps

SDK overview

Versioning and support

Management API

API keys

​Requirements

​Install

​Create a client

​Choose a surface

​Shared API behaviour

​Pagination

​Retries and rate limits

​Idempotency and ETags

​Errors

​Next steps

SDK overview

Versioning and support

Management API

API keys

Requirements

Install

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps