Skip to main content
Use the Go SDK when your application needs importable clients for the Sending, Mailbox, or Management API.
Sending and Mailbox clients require mailbox-scoped smx_mbx_ keys. 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
}

​
Choose a surface

SurfaceImport pathFactoryAPI key
Sendingsendmux.ai/go/sendingsending.Newsmx_mbx_
Mailboxsendmux.ai/go/mailboxmailbox.Newsmx_mbx_
Managementsendmux.ai/go/managementmanagement.Newsmx_root_
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.