# domains.update

Update domain settings.

Updates domain configuration flags (enabled, sending/receiving, alias targets, autodiscovery protocols).

```ts
openemail.domains.update(
  domain: string,
  body?: DomainsUpdateBody,
  options?: CallOptions,
): ApiPromise<Domain>
```

It calls `PATCH /domains/{domain}`: [Update domain settings](/docs/api/domains/patch_DomainUpdate) in the API reference.

## Example

```ts
const result = await openemail.domains.update(domain, {})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `domain` | `string` | Domain name (e.g. 'example.com'). The path's `{domain}`. |
| `body` | [`DomainsUpdateBody`](#domainsupdatebody) | Optional. The request's body. |

## Options

It takes no options of its own. Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`Domain`](/docs/sdks/typescript/types/domain). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed (the body is strict: an unrecognized field is refused, never silently dropped), empty_patch, invalid_domain (an aliasOf that fails D3 canonicalization or D5's mixed-script refusal), send_receive_exclusive (the post-patch state would be both sendOnly and receiveOnly), alias_self, unknown_domain (alias target), alias_cross_account (system caller: the target belongs to a different account than the alias domain), alias_chain, or alias_fbl_exclusive |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | sending_not_writable: `sendVerified` and `sendHold` are operator state — account callers earn sending by publishing DNS and re-POSTing /domains, and a hold its owner could lift is not a hold. Refused for ANY value of either from a non-system caller. ingestion_not_writable: the fbl/dmarc ingestion flags are operator state, so only a system caller may turn one on (an owner may turn them off, and may re-send an unchanged value; a re-send racing an operator's revoke is refused, never re-enabled, and then nothing else in the patch is applied either). dns_status_not_writable, dnsStatus is the platform's resolved verdict, written by POST /domains/:domain/dns/check |
| `404` | Domain not found or not accessible to this principal |
| `409` | domain_in_use, domain_is_alias_target, alias_fbl_exclusive, alias_conflict, account_deleted, or domain_transition_in_progress |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `502` | upstream_unavailable — domain lifecycle transition unavailable |
| `503` | temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description) |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### DomainsUpdateBody

```ts
/** The body of `domains.update`. */
type DomainsUpdateBody = {
  /** Target domain to alias, or null to remove alias */
  aliasOf?: string | null
  /** Enable CalDAV/CardDAV autodiscovery checks */
  dav?: boolean
  /** Aggregate DMARC report ingestion (enabling is system-only) */
  dmarc?: boolean
  /** Manual DNS status override (system callers only) */
  dnsStatus?: DomainsUpdateBodyDnsStatus | null
  /** Whether the domain is active */
  enabled?: boolean
  /** Feedback loop report ingestion (enabling is system-only) */
  fbl?: boolean
  /** File arriving calendar invitations, cancellations and replies into the recipient's calendar, and let CalDAV clients schedule through the server. False leaves arriving invitations as ordinary mail */
  itip?: boolean
  /** Enable JMAP autodiscovery checks */
  jmap?: boolean
  /** The RECEIVE-ONLY mode — see the create description. `true` drops the send-authentication records from this domain's checklist and verdict; `false` asks for them again. Mutually exclusive with `sendOnly`. */
  receiveOnly?: boolean
  /** Operator enforcement (system callers only). 'disabled' STOPS sending: 403 sending_disabled, a permanent 550 at smtp-in, the queued backlog bounced. 'paused' HOLDS it: 429 sending_paused + Retry-After, a 451 the sending MTA queues, the backlog deferred. null lifts either. Egress only: a held domain still receives. Applies to work already accepted as well: a send in progress stops before its remaining recipients, and queued group fan-out, member deliveries, destination webhooks and forwarding legs from this sender's submissions are deferred under 'paused' and dropped under 'disabled'. Already-queued fan-out legs may run for up to 10 seconds after the change. A retry with the same X-Delivery-Id is refused while the hold is set. */
  sendHold?: ('disabled' | 'paused') | null
  /** The SEND-ONLY mode — see the create description. `true` makes the domain's own MX the authority for its mail everywhere on the platform; `false` receives here again. */
  sendOnly?: boolean
  /** The send-records verdict (system callers only, in both directions). Owners earn it by publishing DNS and re-POSTing /domains; an operator may assert or revoke it outright */
  sendVerified?: boolean
  /** SRS bounce-return namespace (enabling is system-only) */
  srs?: boolean
  /** Whether `+` is a tag delimiter on this domain. Owner-writable in both directions. Read from the canonical domain: inert on an alias */
  subaddressing?: boolean
}
```

### DomainsUpdateBodyDnsStatus

```ts
/** Manual DNS status override (system callers only) */
type DomainsUpdateBodyDnsStatus = {
  dav?: boolean
  dkim?: boolean
  dmarc?: boolean
  jmap?: boolean
  mx?: boolean
  spf?: boolean
}
```

It names these types of the API, each on a page of its own: [`Domain`](/docs/sdks/typescript/types/domain).
