Use maxclicks in Bolt

Connect the app you build in Bolt to customer records, events, and prepared emails in maxclicks. Keep the API key in a server environment and make the first request from backend code.

Create a key at https://app.maxclicks.ai/space/-/settings/developers. A key is scoped to one space. Some operations require an admin key.

The existing SDK, CLI, and MCP tools cover an earlier API surface. Use the current REST contract for event readiness/identities, deletion polling, workflow history, and new idempotent operations; see client coverage.

Make a first request over HTTP

This request runs in server-side JavaScript and needs no maxclicks package. Set MAXCLICKS_API_KEY in your server's secret store, then confirm the returned space before making a write.

const apiKey = process.env.MAXCLICKS_API_KEY
if (!apiKey) throw new Error('Set MAXCLICKS_API_KEY first')

const response = await fetch('https://api.maxclicks.ai/v1/me', {
  headers: { Authorization: `Bearer ${apiKey}` },
})
const result = await response.json()
if (!response.ok) throw new Error(result.error?.message ?? 'Request failed')
console.log(result.data.space)

For a runtime without process.env, use its server-side secret API. Keep the key out of browser bundles. Follow the API quickstart to sync a contact and send a prepared template.

The SDK examples below assume you have built the Node client from source. Its npm entry is currently a placeholder.

Connect the SDK

1. Install the package

   Ask the Bolt agent to install the SDK, or run the command in the Bolt terminal.

   # Build and install the source SDK described at /sdks/node.
   

   CopyCopied!

   Requires Node.js 18 or newer. Ships both ESM and CommonJS builds.

2. Store the API key

   Add MAXCLICKS_API_KEY to Bolt's environment variables. Never hardcode the key in client code. Call maxclicks from a server route so the key stays server-side.

3. Call the API

   import { Maxclicks } from 'maxclicks'
   
   const mc = new Maxclicks() // reads MAXCLICKS_API_KEY
   
   // Confirm the key and its space
   const me = await mc.me()
   console.log(me.space?.name)
   
   // Upsert a contact by identity (id or slug of the contact schema)
   const contact = await mc.records.upsert('students', {
     email: '[email protected]',
     firstName: 'Ada',
     tags: ['signup'],
   })
   
   // Fire an event, which can trigger a workflow or a webhook
   await mc.events.fire('purchase-completed', { eventId: 'ord_123', amount: 42 })
   
   // Send a template, resolving the recipient by email
   await mc.templates.send(templateId, {
     data: { contact: { email: '[email protected]' } },
   })
   

   CopyCopied!

Configuration

Pass options to the constructor, or set MAXCLICKS_API_KEY and call new Maxclicks().

Errors

On success a call returns the data directly. On failure it throws a typed error, one of the MaxclicksError subclasses.

import { MaxclicksNotFoundError, MaxclicksRateLimitError } from 'maxclicks'

try {
  await mc.records.get('students', 'missing-id')
} catch (error) {
  if (error instanceof MaxclicksNotFoundError) {
    // 404
  } else if (error instanceof MaxclicksRateLimitError) {
    console.log('retry after', error.retryAfterMs)
  }
}

The source SDK retries 429 within its budget. It retries 5xx and transport errors on reads and keyed writes, with backoff and Retry-After. Preserve the operation key and payload; reconcile uncertain outcomes.

Give the Bolt agent write access

To let the Bolt agent manage your space while it builds, point it at the MCP server. It exposes maxclicks as tools: list schemas and attributes, upsert records, fire events, send templates, manage webhooks, and trigger workflows. Authenticate with your API key as a bearer token:

https://mcp.maxclicks.ai/mcp
Authorization: Bearer max_...

Related

• maxclicks Node SDK
• MCP server
• Contacts