Update contact email preferences by ID

Important: This endpoint only supports customer contacts. Leads do not have a customer email preference surface in the public API.

Path Parameters

• id - The Featurebase contact ID (24-character ObjectId)

Request Body

• preferences - A partial map of preference keys to their desired stored status. Only the preferences included in the request are updated; any preferences omitted are left unchanged. At least one preference must be provided.

Supported Preference Keys

• all - Master delivery gate. When unsubscribed, the contact will not receive any emails regardless of the per-category values. Per-category values are still persisted, so flipping all back to subscribed restores the contact's previous granular preferences.
• postUpdates - Status changes and updates on posts the contact interacts with.
• postComments - New comments on posts the contact follows.
• commentReplies - Replies to the contact's own comments.
• changelog - New changelog releases.

Per-key Values

• subscribed - The contact will receive this email category (subject to the all gate).
• unsubscribed - The contact will not receive this email category.

Combining all with per-category keys

You can send all together with any per-category keys in the same request. The full map is applied atomically as the contact's new stored state — there is no implicit reset of the other keys. This makes the endpoint safe for preference-center UIs that POST the entire form state on submit.

The computed per-category result (after applying the all gate) is surfaced as effectiveStatus in the response, while status reflects the value actually stored for that key.

Example Request (partial update)

{
  "preferences": {
    "postUpdates": "unsubscribed",
    "changelog": "subscribed"
  }
}

Example Request (full preference-center submit)

{
  "preferences": {
    "all": "subscribed",
    "postUpdates": "subscribed",
    "postComments": "unsubscribed",
    "commentReplies": "unsubscribed",
    "changelog": "unsubscribed"
  }
}

Example Response

{
  "object": "contact_email_preferences",
  "contactId": "676f0f6765bdaa7d7d760f88",
  "userId": "usr_12345",
  "email": "john@example.com",
  "preferences": {
    "all": {
      "status": "subscribed",
      "effectiveStatus": "subscribed"
    },
    "postUpdates": {
      "status": "subscribed",
      "effectiveStatus": "subscribed"
    },
    "postComments": {
      "status": "unsubscribed",
      "effectiveStatus": "unsubscribed"
    },
    "commentReplies": {
      "status": "unsubscribed",
      "effectiveStatus": "unsubscribed"
    },
    "changelog": {
      "status": "unsubscribed",
      "effectiveStatus": "unsubscribed"
    }
  }
}