# Email preferences tools

> MCP tools for Email preferences: email_preferences_get, email_preferences_update.

- `email_preferences_get`: Get your email preferences
- `email_preferences_update`: Update your email preferences

## `email_preferences_get`

**Get your email preferences.** Operation [`email_preferences.get`](https://ownrecord.io/docs/reference/email-preferences-get.md) · Platform level · permission `account:read` · risk tier `read` · since M12

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.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument | Type   | Required | Description        |
| -------- | ------ | -------- | ------------------ |
| `token`  | string | no       | (1–200 characters) |

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A signed-in user sent a link token.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person, or the email-preferences link isn't valid.

### Example

**Defaults**

Arguments:

```json
{}
```

Result `output`:

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

## `email_preferences_update`

**Update your email preferences.** Operation [`email_preferences.update`](https://ownrecord.io/docs/reference/email-preferences-update.md) · Platform level · permission `account:write` · risk tier `write` · since M12

Turns topics of Ownrecord's own emails on or off for your account: `onboarding_nudges`, `usage_summary`,
`product_updates` (marketing: off until you opt in here) and `subprocessor_changes`. Account emails can't be
turned off. Each change is recorded with its time and where it was made.

Any signed-in user, for their own account. The link at the bottom of Ownrecord's emails changes the
preferences of the user it was sent to, without a sign-in.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type                                                     | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token`           | string                                                   | no       | (1–200 characters)                                                                                                                                                                                       |
| `topics`          | object                                                   | yes      | –                                                                                                                                                                                                        |
| `source`          | one of `preferences_page`, `subprocessor_page`, `signup` | no       | –                                                                                                                                                                                                        |
| `idempotency_key` | string                                                   | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                                                  | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): No topic was given, a topic isn't one of the four, or a signed-in user sent a link token.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): The caller isn't a signed-in person, or the email-preferences link isn't valid.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The user doesn't exist.
- [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict): The preferences changed at the same time; retry.

### Example

**Opt in to product updates**

Arguments:

```json
{
  "topics": {
    "product_updates": true
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```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": true,
      "changedAt": "2026-10-27T09:00:00.000Z"
    },
    {
      "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": "2026-10-27T09:00:00.000Z"
}
```