chimpmatic-mailchimp-subscribe

A drop-in Mailchimp newsletter subscribe form for React and Next.js. Your API key stays on the server — never exposed to the browser.

Install

npm install chimpmatic-mailchimp-subscribe

Quick Start (Next.js App Router)

1. Create the API route

// app/api/subscribe/route.js
import { handleSubscribe } from 'chimpmatic-mailchimp-subscribe/handler'

export async function POST(request) {
  const data = await request.json()

  const result = await handleSubscribe(
    {
      apiKey: process.env.MAILCHIMP_API_KEY,
      audienceId: process.env.MAILCHIMP_AUDIENCE_ID,
    },
    data
  )

  return Response.json(result.body, { status: result.status })
}

2. Add the form to your page

'use client'

import { SubscribeForm } from 'chimpmatic-mailchimp-subscribe'

export default function Newsletter() {
  return (
    <SubscribeForm
      fields={[
        { tag: 'FNAME', name: 'First Name' },
        { tag: 'LNAME', name: 'Last Name' },
      ]}
    />
  )
}

3. Set your environment variables

MAILCHIMP_API_KEY=your-api-key-us21
MAILCHIMP_AUDIENCE_ID=your-audience-id

That's it. Three files, zero configuration.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | action | string | "/api/subscribe" | API endpoint URL | | fields | FieldConfig[] | [] | Custom merge fields to display | | buttonText | string | "Subscribe" | Submit button label | | placeholder | string | "[email protected]" | Email input placeholder | | successMessage | string | "You're subscribed!" | Message on success | | className | string | — | CSS class for the form | | onSuccess | (email: string) => void | — | Callback on success | | onError | (error: string) => void | — | Callback on error |

FieldConfig

{ tag: string, name: string }

• tag — Mailchimp merge field tag (e.g. FNAME, LNAME, PHONE)
• name — Human-readable label used as placeholder text

Styling

The component uses inline styles by default for zero-config usage. Override with the className prop and your own CSS:

<SubscribeForm className="my-form" />

.my-form input { /* your styles */ }
.my-form button { /* your styles */ }

Server Handler

The handleSubscribe function handles all Mailchimp API communication:

import { handleSubscribe } from 'chimpmatic-mailchimp-subscribe/handler'

const result = await handleSubscribe(
  { apiKey: '...', audienceId: '...' },
  { email: '[email protected]', mergeFields: { FNAME: 'Jane' } }
)

// result.ok — boolean
// result.status — HTTP status code
// result.body — { message } or { error }

Works with any Node.js server framework (Next.js, Express, Fastify, etc.).

Need a full template?

Check out mailchimp-newsletter-subscribe-form — a complete Next.js template with a built-in setup wizard. One-click deploy to Vercel.

License

MIT — ChimpMatic