Go SDK

Build a maxclicks integration into your Go service. Sync customer data, fire events, and trigger prepared experiences with context-aware requests and typed results.

Current API coverage

The SDK groups Public API calls by resource. Use the API reference for request fields, response payloads, and operation semantics, and the examples below for language-specific method calls.

Pagination helpers follow the API traversal limits. An iterator or method named all stops at the traversal cap; use scoped queries when working with larger datasets.

Install

go get github.com/maxclicks-ai/maxclicks-go

Quickstart

The client reads MAXCLICKS_API_KEY from the environment, or pass a key with WithAPIKey. The key is not validated at construction: a missing key surfaces as *maxclicks.ConfigurationError on the first authenticated call.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/maxclicks-ai/maxclicks-go"
)

func main() {
	client := maxclicks.New(maxclicks.WithAPIKey("max_..."))

	ctx := context.Background()

	me, err := client.Me(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("space:", me.Space.Slug)

	contact, err := client.Records.Upsert(ctx, "students", maxclicks.RecordInput{
		"email":     "[email protected]",
		"firstName": "Ada",
		"tags":      []string{"vip"},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("contact id:", contact.ID)
}

Configuration

maxclicks.New accepts functional options.

Errors

Every failure is a typed error. HTTP error responses map by status. Use errors.As against a specific type, or maxclicks.AsAPIError against the base *maxclicks.APIError.

_, err := client.Schemas.Get(ctx, "does-not-exist")

var notFound *maxclicks.NotFoundError
if errors.As(err, &notFound) {
	fmt.Println("missing:", notFound.Message, notFound.Code)
}

if apiErr, ok := maxclicks.AsAPIError(err); ok {
	fmt.Println(apiErr.Status, apiErr.Type, apiErr.Code, apiErr.Message)
}

var rateLimit *maxclicks.RateLimitError
if errors.As(err, &rateLimit) {
	time.Sleep(rateLimit.RetryAfter)
}

Every HTTP error type embeds *APIError, which carries Status, Code, Type, Message, Issues, Header, and RawBody. Issues is populated for validation-gate failures (such as broadcasts.send's broadcast_invalid) that report several problems at once. 402 signals insufficient_credits (an AI-generation or auto-fill call) or email_limit_reached (a send past the email allowance).

Retries are limited to what is safe to repeat. Reads retry on 429, any 5xx, and transport or timeout errors, up to WithMaxRetries extra attempts. A write retries on those only when you pass WithIdempotencyKey, since the server then collapses the repeat into the original; a keyless write that times out or hits a 5xx is reported to you instead of being sent again, so your code can inspect the outcome. The client also retries 429 responses according to its configured retry budget. Backoff is exponential with full jitter, and a Retry-After header (seconds or HTTP date) sets the delay floor.

Pagination

List endpoints return a *maxclicks.Page[T] and a matching ...All iterator that walks every page (stopping when hasMore is false or the maximum offset is reached).

// Single page:
page, err := client.Records.List(ctx, "students", &maxclicks.ListOptions{Limit: 100})
for _, r := range page.Data {
	fmt.Println(r.ID)
}
if page.HasNextPage() {
	page, err = page.NextPage(ctx)
}

// Auto-pager over every record:
it := client.Records.ListAll(ctx, "students", nil)
for it.Next(ctx) {
	fmt.Println(it.Value().ID)
}
if err := it.Err(); err != nil {
	log.Fatal(err)
}

client.Events.List is cursor-paginated, not offset-paginated. It returns a *maxclicks.CursorPage[Event] and a matching ListAll iterator, reading ready events within the selected time window. HasNextPage, NextPage, and Iterator work the same way.

Records and events preserve unknown custom-attribute keys in an Extra map[string]any field alongside the typed base fields.

Idempotency

Mutating endpoints the API documents as idempotency-aware accept maxclicks.WithIdempotencyKey(...) as a trailing option. A retry with the same key replays the original result instead of executing twice.

key := uuid.NewString()
contact, err := client.Records.Upsert(ctx, "students",
	maxclicks.RecordInput{"email": "[email protected]"},
	maxclicks.WithIdempotencyKey(key),
)

Pass an idempotency key to writes such as Records.Create, Records.Upsert, Suppressions.BatchCreate, Suppressions.BatchDelete, Templates.Send, Broadcasts.Send, and Workflows.Trigger. See the supported API writes and retry contract before replaying an operation.

Warnings

The API returns non-fatal warnings in the response body (warnings array), or, for the empty-body Workflows.Trigger response, in the maxclicks-Warning-Message header. Register a handler to observe them.

client := maxclicks.New(
	maxclicks.WithAPIKey("max_..."),
	maxclicks.WithOnWarning(func(warnings []string, method, path string) {
		log.Printf("warning on %s %s: %v", method, path, warnings)
	}),
)

*Page[T] also exposes the warnings for that page as page.Warnings.

Resource surface

Methods are grouped by resource on the client. Each list method also exposes a matching ...All auto-paging iterator.

Notable behaviors:

• Events.FireBatch returns a *BatchFireResult even when the API responds 422 (a batch with failed items is a business result, not an error). Pass maxclicks.BatchOnErrorContinue or maxclicks.BatchOnErrorAbort.
• Templates.Send is synchronous and returns a *TemplateSendResponse. A genuine send failure comes back as Status: "failed" with a generic Error. Pre-send validation and eligibility failures are typed errors.
• Workflows.Trigger returns an empty body. Its path segment is a workflow-step reference, not a workflow id.
• Forms.ConfirmDoubleOptIn and Emails.UnsubscribeOneClick follow the browser redirect and return a *RedirectResult with the final landing URL.

Create schemas, attributes, domains, senders, topics, templates and broadcasts in the maxclicks app, then use resource methods to read them or act on prepared work. Manage API keys and CSV imports in the app. See the API reference for request fields and response details.

Rate limits

Per API key: 100 read requests per second and 25 write requests per second. Exceeding a limit returns 429. The SDK retries automatically, honoring Retry-After.

Retry outcomes

A repeated write can return a recorded result, including an error. If the API reports idempotency_outcome_unknown, inspect the affected resource or run history before creating a new operation. Keep the original key and payload while you reconcile. See the idempotency guide for supported operations and retention.