Update notification email preferences
Partially updates the caller's notification email preferences and returns the full resolved set for all five categories after the change.
Partially updates the caller's notification email preferences and returns the full resolved set for all five categories after the change. Send a preferences object mapping one or more categories to a boolean, e.g. {"preferences":{"billing":false,"usage":true}}; only the named categories change and the rest are left untouched. The map must name at least one category, every key must be one of account, billing, usage, security, or product, and every value must be a boolean — an empty map, an unknown category, or a non-boolean value is rejected with 400 so a typo can never silently no-op. Each category is upserted, so re-sending the same value is a safe no-op. Requires the account:write scope; a read-only key cannot mute a user's security notifications.
Scope: account:write. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Body
Required, application/json: NotificationPreferencesUpdateRequest.
| Field | Type | Required | Description |
|---|---|---|---|
preferences | object | yes | A partial map of category -> emailEnabled. At least one known category is required; unknown category keys are rejected. |
Response
200 Success. Body: application/json, NotificationPreferencesResponse.
| Field | Type | Required | Description |
|---|---|---|---|
object | "notification_preferences" | yes | |
preferences | array of NotificationPreference | yes | One entry per notification category, with its resolved emailEnabled flag. |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
422 | The request is well-formed but a field failed validation (validation_failed). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |