Newsletter middleware

For newsletter systems without a ready-made go~mus integration there is a generic handover. go~mus sends every new subscriber to your URL over HTTP and deletes the record afterwards. What runs behind that URL is up to you. go~mus does not see it.

This path leaves you the work go~mus would otherwise do. In return you keep full control, and all newsletter data in one place.

The flow

1. Someone subscribes in the online shop checkout, through a widget, in the customer profile, or by hand in the back office. go~mus creates the subscriber in the selected newsletter list.

2. On creation go~mus calls your URL immediately, without waiting for a confirmation.

3. If you acknowledge receipt, go~mus deletes the subscriber.

4. Everything after that happens on your side.

The contract

Request. go~mus sends a POST with Content-Type: application/json to the URL configured on the newsletter list. The body has five fields:

Field	Content
`apikey`	The token from the newsletter list. Use it to check whether the call comes from your instance.
`email`	Always set, and the only mandatory field on the go~mus side.
`firstname`	First name, may be empty.
`lastname`	Last name, may be empty.
`salutation`	Salutation, may be empty.

Response. The handover succeeds only on a 2xx status code and a JSON object in the body whose Success field is true. A valid body is:

{"Success": true}

Everything else counts as a failure. That includes a 200 with an HTML error page, an empty body or a JSON array. go~mus deliberately deletes the subscriber only once your system explicitly confirms it took over.

Retries. On failure the background job repeats the handover several times. Your endpoint has to tolerate the same address more than once. Create idempotently: same address plus same list means one subscriber, not a second.

What you take over completely

Plan for these tasks before you switch the first list over.

Double opt-in. With a handover configured, go~mus sends no confirmation mail: either go~mus runs the newsletter itself and sends the double opt-in, or the handover is active and go~mus sends nothing. There is no mixed mode.

We recommend double opt-in in your system. That documents the consent where you have to prove it, without reconciling state between two systems. go~mus hands over a request, not a confirmed consent. Send the confirmation mail yourself, and only add the address to your sending list once it is confirmed.

Unsubscribes. After the handover go~mus no longer knows the subscriber. There is no way back. Unsubscribe link, unsubscribe processing and suppression list are yours.

The list. Who subscribed is no longer recorded in go~mus. The customer profile shows nothing, because the record is deleted. If the same person ticks the box there again, go~mus creates a new subscriber and calls your endpoint again. Another reason to create idempotently.

Data subject rights. Access, rectification and erasure for newsletter data are yours to serve. go~mus no longer holds the data.

Why this path is data-minimal

go~mus keeps no newsletter addresses. So there is no second set of records going stale, no further place to search on an erasure request, and no unnoticed copy in an export. Newsletter data lives with you only.

The flip side: no second system carries any of the load for you.

Setup

In the back office, create one group per newsletter list, with three settings:

Provider: pick the entry for the generic handover. It is labelled "Webhook / Middleware" in the back office.
URL: your endpoint, https please.
Token: your key. It arrives as apikey in the body of every call.

You can create several lists, for example "general", "family programme" and "press", each with its own URL and token. You decide whether one middleware with several targets or separate endpoints sit behind them.

When nothing arrives

The subscriber stays in go~mus. go~mus did not count your response as a success. Check the body before the status code: a missing or misspelled Success is the most common reason.
The same address arrives several times. That is a retry after an attempt counted as a failure, or the result of the box being ticked again in the customer profile. Handle both through idempotency, not through a block.
Nothing arrives at all. Check that provider, URL and token are set. If one is missing, no handover happens and the subscriber stays in go~mus.