---
title: "Request a mail-agent settings change (human approval required)"
method: PATCH
path: "/account/settings"
tags: ["Account"]
---

# Request a mail-agent settings change (human approval required)

`PATCH /account/settings`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/account/settings`
- Auth: HTTP bearer

Credentials cannot change the workspace's email approval authority. A valid request containing `emailKeywordApprovalEnabled` returns **403 `forbidden`**, even with `settings:write`, and even if the requested value already holds. No setting or audit row is written. Ask the workspace owner to enable or disable keyword replies in the InkSeal dashboard.

The endpoint remains available for existing clients. The `settings:write` scope is still checked first; a credential without it receives `insufficient_scope`. A missing or invalid boolean receives 400 `validation_error`. Agent guardrails (`agentSendApproval`, `recipientDenyList`, `apiAccessPaused`) are also human-only.

Use `GET /account/settings` with `account:read` to read the owner-of-record's effective flag. When enabled by that person, a DKIM-valid reply from an authorized sender may approve the reviewed draft.

## Headers

- `Idempotency-Key` string

## Request body

- AccountSettingsUpdateRequest: Legacy request shape. Credential writes to email approval authority return 403 forbidden, including no-op writes.
  - `emailKeywordApprovalEnabled` boolean, required: Human-only email approval preference. Credential writes to this field return 403 forbidden; ask the workspace owner to change it in the dashboard.

## Response `200`

Legacy success shape retained for client compatibility. Credential requests cannot change this preference and valid writes now return 403 forbidden.

- object
  - `data` AccountSettingsUpdateResult, required: Legacy success shape retained for client compatibility. Credentials cannot receive a successful settings change: valid keyword approval writes return 403 forbidden.
    - `emailKeywordApprovalEnabled` boolean, required: The value that now holds for the workspace.
    - `changed` boolean, required: False when the stored value already matched, in which case nothing was written and no audit row was recorded.
    - `agentSendApproval` 'none' | 'required', required: Whether a send made by a service credential waits for a person. `required` parks every credential-initiated `sendEnvelope` as a pending approval, emails the workspace owner, and answers 202 `pending_approval`. Read-only here: a credential that could relax this would make it decorative, so it is changed by a person in the dashboard.
    - `recipientDenyList` string[], required: Addresses and domains no service credential may send to. An entry with an `@` matches that address; an entry without one matches that domain and its subdomains. Read-only here, like `agentSendApproval`.
    - `apiAccessPaused` boolean, required: True while every service credential in this workspace is paused. A paused workspace answers 401 `unauthorized` to every API and MCP request, exactly as a revoked key does, so reading this field back is only possible when it is false. Read-only here.

## Other responses

- `400`: The request is malformed or the resource is in the wrong state for a synchronous check. Codes: `validation_error`, `invalid_body`, `invalid_parameter`, `invalid_idempotency_key`, `invalid_event_id`, `invalid_file`, `invalid_url`, `invalid_status`, `key_mismatch`, `no_signers`, `not_completed`, `envelope_exists`, `document_not_ready`, `upload_failed`.
- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: `forbidden`: credentials cannot change email approval authority or agent guardrails; valid keyword approval settings writes are always refused. Also `insufficient_scope` when settings:write is missing.
- `409`: The resource's state forbids this transition, or another request owns the work. Codes: `invalid_state`, `invalid_status`, `credential_state`, `limit_exceeded`, `envelope_missing`, `not_retryable`, `owner_unavailable`, `workspace_unavailable`, `detection_not_completed`, `document_in_use`, `version_conflict`, `document_processing`, `document_processing_failed`, `normalized_pdf_unavailable`, `pages_not_rendered`, `document_not_ready`, `idempotency_in_progress` (which also carries `Retry-After`), `payment_replayed` (a USDC payment signature presented twice), `payment_pending` (a USDC settlement whose outcome is not yet known).
- `422`: The request parsed but its content is not acceptable. Codes: `validation_error` (envelope configuration, with an `issues` array in `details`), `invalid_envelope`, `envelope_not_ready`, `document_page_limit`, `idempotency_key_reuse`.
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

[API](https://skmtc.dev/inkseal/apis/inkseal-api.md) · [All operations](https://skmtc.dev/inkseal/apis/inkseal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inkseal/apis/inkseal-api/revisions/c440c981d578?raw)