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.

Start with the HTTP request below to verify your workspace, then install the Node SDK for typed API calls in your application.

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 examples below use the Node SDK, which provides types, pagination helpers, and typed errors.

Connect the SDK

1. Install the package

   Install the SDK in your application:

   npm install maxclicks
   

   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 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

Start with the agent onboarding brief: give the agent the current API reference, an environment-based key, and a read-only first task. It can write the HTTP integration without installing a maxclicks client.

To give your agent callable tools, connect the MCP server. Verify the connection with whoami before using tools that change records or send email.

Related

• maxclicks Node SDK
• MCP server
• Contacts