Use maxclicks in v0

Connect the app you build in v0 to customer data and prepared campaigns in maxclicks. In a Next.js project, make API requests from server code such as a Route Handler or Server Action.

The SDK authenticates with an API key. Keep it on the server. Never import maxclicks into a Client Component or expose the key to the browser.

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

1. Install the SDK

   Tell v0 to add the package, or run it yourself. Node.js 18 or newer is required.

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

   CopyCopied!

2. Set the API key

   Add MAXCLICKS_API_KEY to your v0 project's environment variables. Create the key in maxclicks under Settings, Developers, API keys. It looks like max_....

   MAXCLICKS_API_KEY=max_...
   

   CopyCopied!

3. Call the API from server code

   Construct the client once. With no arguments it reads MAXCLICKS_API_KEY and uses https://api.maxclicks.ai/v1.

   import { Maxclicks } from 'maxclicks'
   
   const mc = new Maxclicks() // reads MAXCLICKS_API_KEY
   

   CopyCopied!

Server Action

Use a Server Action to write from a form. This runs on the server, so the key stays private.

'use server'
import { Maxclicks } from 'maxclicks'

const mc = new Maxclicks()

export async function subscribe(email: string, firstName: string) {
  return mc.records.upsert('students', { email, firstName, tags: ['beta'] })
}

upsert matches on contact identity (userId first, then email, then phone), so submitting the same person twice updates one contact instead of creating a second.

Route Handler

Use a Route Handler when v0 code, or an external caller, posts JSON to an endpoint.

import { Maxclicks } from 'maxclicks'

const mc = new Maxclicks()

export async function POST(request: Request) {
  const { email, firstName } = await request.json()
  const contact = await mc.records.upsert('students', { email, firstName })
  return Response.json(contact)
}

Common calls

The first argument is a schema id or slug. Records are flat: base fields plus your own attribute values, all at the top level.

await mc.me() // current key and space
await mc.records.upsert('students', { email }) // create or update a contact
await mc.events.fire('purchase-completed', { eventId: 'ord_123', amount: 42 })
await mc.templates.send(templateId, { data: { contact: { email } } })
await mc.workflows.trigger('7Qk2ZbN4x9LmR3vTpW8sHc0F', { orderId: 'A-1024' })
await mc.forms.submit(formId, { contact: { email } })

Every list returns a Page that is both one page and an async iterable over all pages.

for await (const record of await mc.records.list('students')) {
  console.log(record.id)
}

Errors

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

The SDK retries 429, 5xx, and transport errors with jittered exponential backoff, honoring Retry-After.

import { Maxclicks, MaxclicksConflictError } from 'maxclicks'

const mc = new Maxclicks()

try {
  await mc.records.create('students', { email: '[email protected]' })
} catch (error) {
  if (error instanceof MaxclicksConflictError) {
    // identity already exists; use upsert instead
  }
}

Related

• Node SDK reference
• MCP server
• Agent skills
• Contacts