SDKs

Use an official maxclicks SDK to connect customer data, send events, and trigger prepared campaigns from your application. Choose from eight languages, install the package, and authenticate with your API key.

Each guide covers installation, client configuration, requests, pagination, errors, and retries. For a walkthrough of the underlying requests and responses, follow the HTTP quickstart.

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 SDKs use Public API v1. Follow your language guide for method names and options, and the API reference for request fields, response states, and endpoint behavior.

Capability	Integration guidance
Event acceptance and readiness	Save the acceptance receipt and check readiness before relying on downstream processing.
Event identity changes	Follow the identity contract and preserve operation IDs across retries.
Record deletion	Save the deletion operation ID and poll its status until completion.
Event batch results	Inspect each result, including rolled-back operations and acceptance receipts.
Workflow history	Continue through history pages using the cursor returned by the run.
Idempotent writes	Send a unique key for each logical operation on supported endpoints, and reuse it for retries.

The CLI and MCP server provide terminal and assistant interfaces. Every API reference endpoint also includes direct HTTP examples.

Install

Install the package for your application's language. Follow the linked guide for dependency configuration and a first request.

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`	`npm install maxclicks`	Node.js 18+
Python	`maxclicks`	`pip install maxclicks`	Python 3.9+
PHP	`maxclicks/maxclicks-php`	`composer require maxclicks/maxclicks-php`	PHP 8.1+
Ruby	`maxclicks`	`gem install maxclicks`	Ruby 2.7+
Java	`ai.maxclicks:maxclicks-java`	Add a Maven or Gradle dependency	Java 17+
Rust	`maxclicks`	`cargo add maxclicks`	Rust 1.70+
Elixir	`maxclicks`	Add the Hex dependency	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
Pass an idempotency key on supported writes using the option documented in your language guide. Use a fresh key for each logical operation and preserve it across retries. Reusing one constant can cause unrelated calls to replay the first result. 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.