> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pause Domain

> Take a domain out of the rotation pool without removing it.

## Authentication

Requires x402-verified wallet identity (`X-Payment-Proof` header). Same
auth surface as `/email/quote`.

## Path Parameters

<ParamField path="domain" type="string" required>
  The bare domain to pause — e.g. `oneshotagents.com`. Must be owned by
  the caller (`domains.agent_id = wallet`).
</ParamField>

## Behavior

Sets `pool_status` to `paused` on the matching row. The rotation selector
skips paused domains entirely. Allowed transitions:

| From      | Result                                                                            |
| --------- | --------------------------------------------------------------------------------- |
| `active`  | → `paused`                                                                        |
| `warming` | → `paused` (legitimate "take it out of consideration" before warmup graduates it) |
| `paused`  | no-op                                                                             |
| `removed` | not found                                                                         |

Returns `404 domain_not_found` if the domain isn't owned by the caller or
is `removed`.

## Response

<ResponseField name="domain" type="string">
  The paused domain.
</ResponseField>

<ResponseField name="pool_status" type="string">
  `paused`.
</ResponseField>

<ResponseField name="warmup_state" type="string">
  Reputation health (`warming` | `warmed` | `degraded`) — unchanged by a
  manual pause, since pausing rotation doesn't stop warmup.
</ResponseField>

<ResponseField name="pause_reason" type="string">
  `manual` — a manual pause stays paused until you
  [resume](/api-reference/email/domain-resume) it; the reconciler will not
  auto-recover it (unlike a `low_reputation` pause).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST \
    https://win.oneshotagent.com/v1/tools/email/domains/oneshotagents.com/pause \
    -H "X-Payment-Proof: <your_x402_signature>"
  ```

  ```typescript SDK theme={null}
  await sdk.email.pauseDomain('oneshotagents.com');
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  { "domain": "oneshotagents.com", "pool_status": "paused", "warmup_state": "warmed", "pause_reason": "manual" }
  ```
</ResponseExample>

## Notes

* Pausing does NOT release the domain or stop renewals. It just gates the
  rotation selector from picking it. Reverse with
  [`/domains/:domain/resume`](/api-reference/email/domain-resume).
* Explicit sends (passing `from_address`) bypass the pool, so a paused
  domain can still be used directly — pause only affects server-side
  rotation.
* Pausing a `warming` row is fine, but
  [resume](/api-reference/email/domain-resume) won't bring a
  formerly-warming row back to `active` — only the daily reconciler can
  graduate it (score ≥ threshold).