SDKs

Use a client library to connect customer records, events, and prepared campaigns from the language your team already runs. These guides explain the SDK interfaces alongside the REST API, so you can choose how much of the HTTP handling to manage yourself.

These guides cover eight client interfaces. Source and package availability vary: the Go module resolves from its repository, while the npm maxclicks entry is a placeholder rather than the client shown here. Check your language's installation guide before adding a dependency. The API quickstart works directly with HTTP.

Configure schemas, brand, content, and journeys in the app. Your integration keeps customer data current, triggers the experience, and reads the results. Client libraries follow the same endpoint permissions and limits as direct API requests.

Current API coverage

The REST reference follows the current server. The client sources documented here still wrap an earlier surface. Package availability and contract coverage are separate checks: a library resolving successfully does not mean it exposes every current endpoint.

Current REST capability	Existing client/tool limitation	Use now
Event acceptance receipt and readiness	Older `FireResult` models expose only `accepted`; no readiness method	Fire and poll status over HTTP
Event identity changes	No `event-identities` wrapper	Identity endpoint over HTTP
Record deletion operation	Older deletion models expect `{ id, deleted }`; no polling method	Delete and poll, inspect `status`
Event batch rollback	Older result enums omit `rolled_back` and receipt fields	Inspect the current raw `data.results`, including HTTP `422`
Workflow history beyond the latest 100 entries	No `history_before` option; models omit the cursor	Get run with `nextHistoryBeforeIndex`
Idempotency on 17 writes	Client key arguments cover the original seven operations	Use direct HTTP for the additional supported writes

Dynamic clients may preserve extra JSON fields at runtime; static model decoders can hide them. Do not cast an old type and assume it proves compatibility. The generated cURL and JavaScript examples on every reference endpoint use the current HTTP contract without a library dependency. CLI and MCP tools use the same earlier client surface.

Install

Language	Package	Install	Runtime
Go	`github.com/maxclicks-ai/maxclicks-go`	`go get github.com/maxclicks-ai/maxclicks-go`	Go 1.22+
Node.js	`maxclicks`	Source on GitHub, npm release pending	Node.js 18+
Python	`maxclicks`	Source on GitHub, PyPI release pending	Python 3.9+
PHP	`maxclicks/maxclicks-php`	Source on GitHub, Packagist release pending	PHP 8.1+
Ruby	`maxclicks`	Source on GitHub, RubyGems release pending	Ruby 2.7+
Java	`ai.maxclicks:maxclicks-java`	Source on GitHub, Maven Central release pending	Java 17+
Rust	`maxclicks`	Source on GitHub, crates.io release pending	Rust 1.70+
Elixir	`maxclicks`	Not yet released	Elixir 1.15+

The Python and Ruby SDKs have zero runtime dependencies. Go and Rust use the standard library and reqwest respectively. Java depends on Jackson. PHP uses any PSR-18 client, discovered at runtime.

Quickstart

Start with GET /v1/me through your chosen client. Confirm the key and space before writing customer data or sending email. Each language guide includes its own initialization and request examples.

Store MAXCLICKS_API_KEY on your server. The default base URL is https://api.maxclicks.ai/v1; do not embed the key in client-side code.

When you are ready to write, use the API quickstart to understand the schema and template requirements, then follow the equivalent methods in your SDK guide.

Shared contract

The API contract stays the same across languages. Constructor options, method signatures, and pagination helpers follow each language's conventions; consult the language guide for exact usage.

Name
Authentication
Type
Bearer
Description
The API key is sent as Authorization: Bearer max_.... It falls back to the MAXCLICKS_API_KEY environment variable. The public form and email endpoints (forms.submit, forms.confirmDoubleOptIn, one-click unsubscribe) send no auth header.
Name
Envelope unwrap
Type
{ data }
Description
The API returns a { "data": ... } envelope. SDKs return the unwrapped payload directly. Wire keys stay verbatim (camelCase, for example firstName, namePlural), because records carry arbitrary custom attribute keys.
Name
Pagination
Type
auto
Description
List methods expose pagination information. Use the language-specific page or iterator helpers to traverse results, and respect the offset cap of 10,000. Events use cursor pagination. See pagination.
Name
Errors
Type
typed
Description
Failures surface as typed errors carrying status, code, type, message, response headers, and the raw body. See errors.
Name
Retries
Type
2 (default)
Description
SDKs provide bounded backoff for transient failures. Writes require special care: pass an idempotency key only to a supported endpoint, preserve it across retries, and handle unresolved outcomes. A retry may replay a recorded error; it does not guarantee another execution. See your language guide for its retry options and the idempotency contract.
Name
Idempotency
Type
Idempotency-Key
Description
The API accepts a key on 17 writes. Existing client arguments cover the original seven: record create/upsert, batch suppression create/delete, template send, workflow trigger, and broadcast send. Use direct HTTP where an additional supported method cannot set the header. Pass a fresh key per logical operation, never one reused constant, or the API treats unrelated calls as replays of the first. See idempotency.
Name
Timeout
Type
60s (default)
Description
Per-request timeout, configurable at construction.
Name
Warnings
Type
callback
Description
The API returns non-fatal warnings (for example a clamped limit). Pass an onWarning callback to observe them.

Errors

Each SDK maps HTTP status to a typed error under one base class (MaxclicksError in Node, Maxclicks::Error in Ruby, MaxclicksException in PHP and Java, Maxclicks.Error in Elixir, MaxclicksError in Rust, *APIError in Go).

Status	Meaning
`400`	Validation failure
`401`	Missing or invalid API key
`402`	Insufficient credits or email limit reached
`403`	Insufficient permission
`404`	Resource not found
`409`	Identifier or uniqueness conflict
`413`, `415`	Payload too large, unsupported media type
`422`	Unprocessable (for example a batch abort)
`429`	Rate limited (carries retry-after)
`5xx`	Server error

Transport failures, timeouts, and missing configuration raise their own error types before or instead of an HTTP response. Validation-gate failures (such as broadcasts.send) carry an issues list with each problem.

All SDKs speak Public API v1. Method and argument names follow each language's idiom (camelCase in Node, snake_case in Python and Ruby), but resource names, endpoint behavior, and error taxonomy come from the REST contract. Client source coverage is narrower, as listed above.