# Get your email preferences

> The email_preferences.get operation: GET /api/v1/email_preferences in the REST API and the email_preferences_get tool in the MCP server.

Returns which of Ownrecord's own emails you get. Account emails (welcome, security notices, plan and
billing notices, legal changes) always go out and never contain promotions. The topics here are the ones
you can change: onboarding reminders and the monthly usage summary (on unless you turn them off), product
updates (only if you opt in) and sub-processor changes (subscribe to them; owners and admins of
organizations that accepted the DPA always get them).

Any signed-in user, for their own account.

## At a glance

- **REST:** `GET /api/v1/email_preferences`
- **MCP tool:** `email_preferences_get`
- **Operation ID:** `email_preferences.get`
- **Scope:** Platform
- **Permission:** `account:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `account:read` scope
- **Since:** M12

## Request

### Query parameters

| Field   | Type   | Required | Description |
| ------- | ------ | -------- | ----------- |
| `token` | string | No       |             |

## Response

`200 OK` with a JSON object:

| Field                  | Type                                                                                   | Description |
| ---------------------- | -------------------------------------------------------------------------------------- | ----------- |
| `object`               | `"email_preferences"`                                                                  |             |
| `userId`               | `usr_…` ID                                                                             |             |
| `topics`               | array of object                                                                        |             |
| `topics[].topic`       | one of `onboarding_nudges`, `usage_summary`, `product_updates`, `subprocessor_changes` |             |
| `topics[].label`       | string                                                                                 |             |
| `topics[].description` | string                                                                                 |             |
| `topics[].consent`     | one of `service`, `marketing`                                                          |             |
| `topics[].enabled`     | boolean                                                                                |             |
| `topics[].changedAt`   | date-time or null                                                                      |             |
| `updatedAt`            | date-time or null                                                                      |             |

## Examples

### Defaults

```http
GET /api/v1/email_preferences
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "email_preferences",
  "userId": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "topics": [
    {
      "topic": "onboarding_nudges",
      "label": "Onboarding reminders",
      "description": "A reminder 2 and 7 days after you create an organization, while setup steps are still open.",
      "consent": "service",
      "enabled": true,
      "changedAt": null
    },
    {
      "topic": "usage_summary",
      "label": "Monthly usage summary",
      "description": "Your live volume, Ownrecord fees and an estimate of what a platform merchant of record would cost.",
      "consent": "service",
      "enabled": true,
      "changedAt": null
    },
    {
      "topic": "product_updates",
      "label": "Product updates",
      "description": "A digest of new features from the changelog. Only if you opt in.",
      "consent": "marketing",
      "enabled": false,
      "changedAt": null
    },
    {
      "topic": "subprocessor_changes",
      "label": "Sub-processor changes",
      "description": "Notice of a new or replaced sub-processor, 30 days ahead. Owners and admins of organizations that accepted the DPA always get it.",
      "consent": "service",
      "enabled": false,
      "changedAt": null
    }
  ],
  "updatedAt": null
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                                            | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | A signed-in user sent a link token.                                             | Fix the fields listed in `details.issues` and send the request again.           |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | The caller isn't a signed-in person, or the email-preferences link isn't valid. | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).