Subscribe a customer to a newsletter and manage the subscription

  • Subscriptions
  • Customer account
  • 3 routes
How do I create, review, and update a newsletter subscription?

This scenario describes the journey for subscribing a customer to one or more Club Med newsletters. It covers the initial subscription creation, retrieving the current state through the identifier returned by the API, and updating the subscription to add another newsletter or trigger an unsubscribe operation.

The entry point is POST/v1/subscriptions, which returns a subscription id and a customer_id. This identifier is then used by GET/v0/subscriptions/{subscription_id} to read the current subscription state, and by PATCH/v1/subscriptions/{subscription_id} to execute either a subscribe or an unsubscribe operation.

Overview

This journey lets you manage a customer newsletter subscription using a technical subscription identifier.

The subscription is created with POST/v1/subscriptions. Its state is read with GET/v0/subscriptions/{subscription_id}. It is updated with PATCH/v1/subscriptions/{subscription_id}.

The most credible functional sequence is the following:

Prerequisites

  • Have the x-api-key header
  • Provide the accept-language header with a valid locale, for example fr-FR
  • For read and update operations, have a subscription_id obtained from the POST call
  • For an additional subscribe operation through PATCH, know a valid newsletter_subscriptions value
  • The full request body schema for POST/v1/subscriptions is not verifiable with the available sources
  • The description of POST/v1/subscriptions indicates that personal information is expected, that the target newsletters must be specified, that the contact channel must be provided, and that either Gender or Civility is mandatory

Important

POST/v1/subscriptions can fail if opt-ins and provided fields are inconsistent, if a subscription already exists for the customer, or if optin is not set to true.

Preparing newsletter IDs

The GET/v0/newsletters route exists and lets you retrieve the list of subscribable newsletters, for example CLUBMED. It is useful before starting the main journey.

Process workflow

Legend:
Mandatory
Optional
1

Create the newsletter subscription

Mandatory

This route creates a newsletter subscription from the customer's personal information.

Prerequisites

Send the contact details, the target newsletters, and a contact channel. According to the Swagger contract, the body must also include either Gender or Civility.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "country": "FR", "newsletter_subscriptions": ["CLUBMED"], "channel": "EMAIL", "gender": "FEMALE", "optin": true}' \
  "https://api.clubmed.com/v1/subscriptions"

Example answer

{
  "id": "subscription-1",
  "customer_id": "123456789"
}

info: Keep the returned subscription identifier: it is required to review or update the consent later on.

Response codes

  • 200 OK or 201 Created: the subscription is created.
  • 400 Bad Request: inconsistent data, existing subscription, or invalid JSON.
  • 403 Forbidden: the country or channel is not allowed.
POST/v1/subscriptions
See more
2

Review the subscription state

Mandatory

This route returns the current state of a newsletter subscription.

Prerequisites

Use the subscription identifier returned at creation time.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  "https://api.clubmed.com/v0/subscriptions/{subscription_id}"

Example answer

{
  "id": "subscription-1",
  "customer_id": "123456789",
  "email": "jane@example.com",
  "phone": "+33600000000",
  "origin_code": "CUSTOMER_ACCOUNT",
  "newsletter_subscriptions": [
    "CLUBMED"
  ],
  "optins": {
    "email": true,
    "sms": false
  }
}

info: You can review opt-ins, active newsletters, and the subscription origin before updating anything.

Response codes

  • 200 OK: the subscription is returned.
  • 400 Bad Request: invalid parameters.
  • 403 Forbidden: access denied.
  • 404 Not Found: subscription not found.
GET/v0/subscriptions/{subscription_id}
See more
3

Update the newsletter subscription

Mandatory

This route updates the newsletter subscription state, for example to unsubscribe or resubscribe.

Prerequisites

Use the subscription identifier and the expected operation in the body, such as unsubscribe or subscribe.

Calling CURL

curl -X PATCH \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: en-US" \
  -H "Content-Type: application/json" \
  -d '{"operation": "subscribe", "parameters": {"newsletter_subscriptions": ["CLUBMED"], "origin_code": "CUSTOMER_ACCOUNT"}}' \
  "https://api.clubmed.com/v1/subscriptions/{subscription_id}"

Example answer

HTTP/1.1 204 No Content

info: Success is returned without a response body. If needed, call the read step again right after the update.

Response codes

  • 204 No Content: the subscription is updated.
  • 400 Bad Request: invalid operation or malformed JSON.
  • 403 Forbidden: access denied.
  • 404 Not Found: subscription not found.
PATCH/v1/subscriptions/{subscription_id}
See more