# Customers in a mailing tool

Source: https://developers.weerom.com/docs/use-cases/newsletter

> Keep a Mailchimp or Brevo list in step with the shop's customers, and only mail the ones who agreed.

**For** a shop that sends a newsletter or a campaign from Mailchimp, Brevo or a CRM, and wants new customers to show up there without a weekly export.

A job reads the customers that changed since its last run and adds or updates each one as a contact, keyed by the customer's `id`. It sends name, email, language and postal code. Whether a person may get marketing mail is the shop's to know: the API does not say.

| What | You need |
| --- | --- |
| Key | **Read key** A read key, on a server. |
| Endpoints | `GET /customers` with `updated_after`. |
| Mailing tool | Your own code that adds a contact in Mailchimp, Brevo or your CRM. |

> **The API does not say who agreed to mail.** A customer object has no mail preference and no consent. WeerOm leaves its own mail preferences out of the API on purpose. A customer who booked a haircut did not, by booking, agree to a newsletter. The shop must have its own consent, under the GDPR, before it mails anyone, for example from a sign-up form on its site. Add customers to the tool as contacts without a subscription, and mark only the ones who agreed as subscribed.

## What a customer holds

```json
{
  "object": "customer",
  "id": "5f0c9d3a-7b2e-4c61-8a4d-9e1f3b6c2d75",
  "name": "Lotte Peeters",
  "email": "lotte@example.com",
  "phone": "+32470123456",
  "locale": "nl",
  "postal_code": "9000",
  "has_account": true,
  "blocked": false,
  "no_show_count": 0,
  "created_at": "2026-04-11T09:05:22.000Z",
  "updated_at": "2026-11-18T14:02:11.000Z"
}
```

| Field | In the mailing tool |
| --- | --- |
| `id` | Your own key for the contact. A customer's email may change, the `id` does not. |
| `email` | The address. `null` for a customer who booked without one: skip them. |
| `name` | One field. WeerOm does not split first and last name. |
| `locale` | The language their mail from the shop goes out in. Use it to pick the campaign's language. |
| `postal_code` | For a campaign by area. `null` when unknown. |
| `blocked` | The shop stopped taking online bookings from them. You may want to leave them out. |

## The job

`upsertContact(customer)` stands for your own code. Fill it in from Mailchimp's or Brevo's own API documentation. This page does not describe either API.

```js title="sync-contacts.js"
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://api.weerom.com/v1";
const STATE_FILE = "./contacts-state.json";

async function weerom(path) {
  const response = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${process.env.WEEROM_KEY}` },
  });
  const json = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${json.error.code}: ${json.error.message}`);
  }
  return json;
}

const state = await readFile(STATE_FILE, "utf8").then(JSON.parse, () => ({ lastUpdatedAt: null }));
let highest = state.lastUpdatedAt;
let cursor = null;

do {
  const query = new URLSearchParams({ limit: "100", order: "asc" });
  if (state.lastUpdatedAt) query.set("updated_after", state.lastUpdatedAt);
  if (cursor) query.set("cursor", cursor);
  const page = await weerom(`/customers?${query}`);

  for (const customer of page.data) {
    if (customer.email) {
      // As a contact, not as a subscriber. Consent comes from the shop.
      await upsertContact({
        email: customer.email,
        externalId: customer.id,
        language: customer.locale,
        name: customer.name,
        postalCode: customer.postal_code,
      });
    }
    if (!highest || customer.updated_at > highest) highest = customer.updated_at;
  }
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);

await writeFile(STATE_FILE, JSON.stringify({ lastUpdatedAt: highest }));
```

The first run reads every customer. A shop with 3,000 customers is 30 requests. The list is sorted by `created_at`, so take the highest `updated_at` from all pages, as the job does.

## How often

Once an hour, or once a night. A newsletter does not need a customer the minute they booked. A quiet run is one request. A change to a customer sends no webhook, so the job asks.

## Limits

- **No consent and no mail preferences.** The API does not expose them. The shop keeps its own record of who agreed.
- **No unsubscribes back.** Someone who unsubscribes in Mailchimp or Brevo stays a customer in WeerOm, and WeerOm's own booking mail keeps going to them. The two lists are separate.
- **No deletions.** A customer the shop erased does not show up as a change. Walk the whole list now and then and remove contacts whose `id` is gone.
- **One-way.** `PATCH /customers/{id}` changes only a name or a block, so the mailing tool cannot write an email or a phone back to WeerOm.
