# routes.update

Update email route.

Updates the destination, delivery pacing, group posting policy, webhook tap, or forward tap for an email address.

```ts
openemail.routes.update(
  address: string,
  body?: RoutesUpdateBody,
  options?: CallOptions,
): ApiPromise<Route>
```

It calls `PATCH /routes/{address}`: [Update email route](/docs/api/routing/patch_RouteUpdate) in the API reference.

## Example

```ts
const route = await openemail.routes.update(address, {})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `address` | `string` | Full email address (e.g. 'info@example.com'). The path's `{address}`. |
| `body` | [`RoutesUpdateBody`](#routesupdatebody) | 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, [`Route`](/docs/sdks/typescript/types/route). 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, invalid_address (malformed remoteAddress), empty_patch, destination_requires_type, posting_requires_group, no_webhook, webhook_format_unavailable, unknown_mailbox (missing, inaccessible, or outside the route domain's account, including platform domains), or destination_is_self / destination_loops / destination_chain_too_long |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Route not found or not accessible to this principal |
| `409` | group_has_persona — a group never changes shape in place (DELETE the route instead: its persona's archive and credential would otherwise be orphaned); mailbox_is_group_persona — the mailbox target is a group's persona; inbound_edge_cap — the destination cannot accept another incoming edge; route_changed — a concurrent edit replaced the publication; primary_address_route (with address and mailboxId): the address is that mailbox's primary address, so it may not be retargeted away from it (a restate onto the same mailbox is fine). Promote another address with PATCH /identities/:id \{primaryAddress\}, clear it with primaryAddress: null, or delete the mailbox |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `429` | rate_limited — converting into a group mints its persona and spends a mailbox-create slot |
| `503` | temporary_failure (with Retry-After): under the object directory, the account's identity census could not be updated just now, so the write that would move it was not made; retry the same request after the Retry-After window (converting into a group, whose persona the census counts) |

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

### RoutesUpdateBody

```ts
/** The body of `routes.update`. */
type RoutesUpdateBody = {
  /** New destination type */
  destinationType?: ('mailbox' | 'webhook' | 'remote' | 'group')
  /** Destination mailbox ID (when destinationType is 'mailbox') */
  mailboxId?: string
  /** Pace inbound deliveries to this route's mailbox through the paced queue (funnel/shared-inbox protection). Mailbox routes only; ignored at delivery time for other destination types. */
  paced?: boolean
  /** Group posting policy ('open' or 'members') */
  posting?: ('open' | 'members')
  /** Destination forwarding address or forward tap address (null to remove tap). An external target may carry a UTF-8 local part (D6); the domain half is canonicalized (D3) */
  remoteAddress?: string | null
  /** Webhook payload format: 'parsed' (default) or 'reference' */
  webhookFormat?: ('parsed' | 'reference')
  /** HMAC signing secret for webhooks (null to clear) */
  webhookSecret?: string | null
  /** Destination webhook URL or tap webhook URL (null to remove tap) */
  webhookUrl?: string | null
}
```

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