Getting Started

Installation

1. Add nuxt-listmonk module to your nuxt.js project:

npx nuxi module add nuxt-listmonk

2. If necessary, add nuxt-listmonk to the modules key on nuxt.config.ts file:

export default defineNuxtConfig({
  modules: ['nuxt-listmonk'],
});

Usage

1. Set up your environment variables:

NUXT_LISTMONK_HOST=""
NUXT_LISTMONK_LIST_ID=""
NUXT_LISTMONK_API_USERNAME=""
NUXT_LISTMONK_API_TOKEN=""

NUXT_LISTMONK_LIST_ID must be the positive numeric ID used by the authenticated Listmonk API. Public list UUIDs previously submitted as the l form field are not accepted.

Create a dedicated Listmonk API user with permission to create and query subscribers and manage subscriptions for the configured list. Keep its access token server-side; none of these values belong in runtimeConfig.public.

2. Add these options to the listmonk key on nuxt.config.ts file:

export default defineNuxtConfig({
  modules: ['nuxt-listmonk'],
  listmonk: {
    host: process.env.NUXT_LISTMONK_HOST,
    listId: process.env.NUXT_LISTMONK_LIST_ID,
    apiUsername: process.env.NUXT_LISTMONK_API_USERNAME,
    apiToken: process.env.NUXT_LISTMONK_API_TOKEN,
    existingSubscriberMode: 'preserve',
  },
});

Subscriptions made by the module are confirmed immediately. When the e-mail already exists, existingSubscriberMode controls how the subscriber is handled:

• preserve (default) adds the configured list without changing the subscriber's name, account status, attributes, or other list memberships.
• merge adds the configured list, updates a submitted name, and merges submitted attributes while preserving unrelated attributes and other list memberships.

Merge mode uses PATCH /api/subscribers/{id} and requires Listmonk 6.1 or newer. The API user must have permission to query and update subscribers as well as manage the configured list. If the profile update fails, the list may already have been added because membership is updated first.

Subscriber attributes

Pass custom Listmonk attributes in the optional attribs object:

await useSubscribe({
  email: '[email protected]',
  name: 'Person',
  attribs: {
    locale: 'pt-BR',
    interests: ['security', 'payments'],
    preferences: {
      frequency: 2,
      enabled: true,
      fallback: null,
    },
  },
})

The attributes root must be a plain object. Values can contain strings, finite numbers, booleans, null, arrays, and nested plain objects. Invalid attribute payloads are rejected before lifecycle hooks or Listmonk are called.