# Get contact email preferences by external user ID

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

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

Endpoint: GET /v2/contacts/by-user-id/{userId}/email-preferences
Version: 2026-01-01.nova
Security: bearerAuth

## Header parameters:

  - `Featurebase-Version` (string)
    API version for this request. Defaults to your organization's configured API version if not specified.
    Example: "2026-01-01.nova"

## Path parameters:

  - `userId` (string, required)
    External user ID from your system
    Example: "usr_12345"

## Response 200 fields (application/json):

  - `object` (string, required)
    Object type identifier
    Enum: "contact_email_preferences"

  - `contactId` (string, required)
    Featurebase contact ID
    Example: "676f0f6765bdaa7d7d760f88"

  - `userId` (string,null)
    External user ID from your system, if available
    Example: "usr_12345"

  - `email` (string,null)
    Contact email address, if available
    Example: "john@example.com"

  - `preferences` (object, required)
    Email preference state for this contact, including both stored status and final effective status.

  - `preferences.all` (object, required)
    Global email preference state for all email notifications.

  - `preferences.all.status` (string, required)
    Stored preference status for this category
    Enum: "subscribed", "unsubscribed"

  - `preferences.all.effectiveStatus` (string, required)
    Final effective status after applying global preference overrides
    Enum: "subscribed", "unsubscribed"

  - `preferences.postUpdates` (object, required)
    Global email preference state for all email notifications.
    Example: {"status":"subscribed","effectiveStatus":"unsubscribed"}

  - `preferences.postComments` (object, required)
    Global email preference state for all email notifications.
    Example: {"status":"subscribed","effectiveStatus":"subscribed"}

  - `preferences.commentReplies` (object, required)
    Global email preference state for all email notifications.
    Example: {"status":"subscribed","effectiveStatus":"subscribed"}

  - `preferences.changelog` (object, required)
    Global email preference state for all email notifications.
    Example: {"status":"subscribed","effectiveStatus":"subscribed"}

## Response 404 fields (application/json):

  - `error` (object, required)

  - `error.type` (string, required)
    The type of error returned
    Enum: "invalid_request_error"

  - `error.code` (string, required)
    Machine-readable error code
    Enum: "contact_not_found"

  - `error.message` (string, required)
    Human-readable error message
    Example: "An error occurred"

  - `error.param` (string)
    The parameter that caused the error (if applicable)
    Example: "id"

  - `error.status` (number, required)
    HTTP status code
    Enum: 404