Featurebase API (2026-01-01.nova)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves the email preference state for a customer contact by their Featurebase 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)

Response Format

Returns a contact email preferences object with:

• object - Always "contact_email_preferences"
• contactId - Featurebase contact ID
• userId - External user ID, if available
• email - Contact email address, if available
• preferences - Current email preference state

Preference Semantics

Each preference includes:

• status - The stored preference state for that category
• effectiveStatus - The final state after applying the global all preference override

Example Response

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

Updates one or more email preferences for a customer contact by their Featurebase 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"
    }
  }
}

Retrieves the email preference state for a customer contact by their external user ID.

This endpoint only supports customer contacts and mirrors the existing by-user-id lookup pattern used across the contact API.

Path Parameters

• userId - The external user ID from your system

Example Response

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