Skip to main content
Contacts

Update contact email preferences by external user ID

Updates one or more email preferences for a customer contact by their external user ID.

PATCH
/v2/contacts/by-user-id/{userId}/email-preferences

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

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.

See PATCH /v2/contacts/{id}/email-preferences for the full list of supported preference keys and per-key values, the all delivery-gate semantics, and details on combining all with per-category keys in a single request.

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"
    }
  }
}

Authorizations

Authorizationstringheaderrequired

API key as Bearer token. Use: Authorization: Bearer sk_...

Path Parameters

userIdstringrequired

External user ID from your system

Maximum string length: 255
Example: usr_12345

Headers

Featurebase-Versionenum<string>header

API version for this request. Defaults to your organization's configured API version if not specified.

Available options: 2026-08-19.orbit, 2026-01-01.nova, 2025-12-12.clover
Example: 2026-08-19.orbit

Body

application/json
preferencesobjectrequired

Response

application/json

Success

contactIdstringrequired

Featurebase contact ID

Example: 676f0f6765bdaa7d7d760f88
emailstring | null

Contact email address, if available

Example: john@example.com
objectenum<string>required

Object type identifier

Available options: contact_email_preferences
Example: contact_email_preferences
preferencesobjectrequired

Email preference state for this contact, including both stored status and final effective status.

userIdstring | null

External user ID from your system, if available

Example: usr_12345

Still need help? Ask the team