Wepublish Mailchimp

A TypeScript wrapper for the Mailchimp Marketing API.

Installation

npm install @wepublish/wepublish-mailchimp

Usage

import { Mailchimp } from "@wepublish/wepublish-mailchimp";

const mailchimp = new Mailchimp("your-api-key");

API

getInfoString(): Promise<string>

Returns a formatted string with all lists, merge fields, and interest groups.

getInfoJson(): Promise<MailchimpInfo>

Returns structured data about all lists, merge fields, and interest groups.

addContact(listId: string, data: ContactData): Promise<void>

Adds or updates a contact in a list.

await mailchimp.addContact("list-id", {
  email: "[email protected]",
  status: "subscribed", // or "pending"
  mergeFields: { FNAME: "John", LNAME: "Doe" },
  interests: { "interest-id": true }
});

getContacts(listId: string): Promise<ListMembersResponse>

Retrieves all contacts from a list with automatic pagination.

getTemplate(nameContains: string): Promise<CampaignTemplate>

Finds a campaign whose title contains nameContains (case-insensitive) and returns it as a read-only snapshot including its HTML content. The original campaign is never modified.

const template = await mailchimp.getTemplate("Dorfkönig-Basis");

getPlaceholders(template: CampaignTemplate): TemplatePlaceholder[]

Parses the template HTML and returns all placeholders with their types. Placeholders follow the convention section:field embedded in the HTML, where the type is inferred from the element context:

| Type | HTML location | Example | |------|--------------|---------| | text | Text content of any <p> or heading (<h1>–<h6>) | <p>dorfkoenig:intro</p> | | image | alt attribute of an <img> element | <img alt="dorfkoenig:heroImage"> | | url | href attribute of an <a> element | <a href="http://dorfkoenig:ctaUrl"> |

const placeholders = mailchimp.getPlaceholders(template);
// [{ key: "dorfkoenig:intro", type: "text" }, { key: "dorfkoenig:heroImage", type: "image" }, ...]

createFromTemplate(template: CampaignTemplate, newName: string, replacements: PlaceholderReplacements): Promise<void>

Creates a new campaign from a template by replacing placeholders with the provided values. Keys in replacements must be the full section:field placeholder string.

• text placeholders: the element's text content is replaced
• image placeholders: the src attribute of the <img> is replaced
• url placeholders: the href attribute of the <a> is replaced

await mailchimp.createFromTemplate(template, "Dorfkönig - 2024-06-01", {
  "dorfkoenig:villageName": "Aesch",
  "dorfkoenig:heroImage": "https://example.com/hero.jpg",
  "dorfkoenig:ctaUrl": "https://example.com/article",
});

The original template campaign is never modified or deleted.

Development

Build

npm run build

Publish

Add the following line to .npmrc:

//registry.npmjs.org/:_authToken=MYTOKEN

npm publish