Go SDK

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

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 for the surface you are calling.

Install

The Go SDK is one module with surface subpackages.

go get sendmux.ai/go@latest

OAuth access tokens

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

package example

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

func oauthClient() (*mailbox.Client, error) {
    return mailbox.NewWithTokenProvider(func(ctx context.Context) (string, error) {
        return os.Getenv("SENDMUX_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. The same token option is available for Sending and Management clients.

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_`

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.

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

Developer tools

AI integrations

Sending

Receiving

Domains

Monitoring

Webhooks

Use cases

Integrations

Account and billing

Requirements

Install

OAuth access tokens

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

​OAuth access tokens

​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

OAuth access tokens

Create a client

Choose a surface

Shared API behaviour

Pagination

Retries and rate limits

Idempotency and ETags

Errors

Next steps