# routes.create

Create a routing rule.

Creates an email routing rule mapping an address to a mailbox, webhook, remote forwarder, or group. For non-webhook destinations an optional webhookUrl attaches a tap that receives a copy of incoming messages; for non-remote destinations an optional remoteAddress attaches a forward tap that relays a copy to another address alongside the delivery. Idempotent: re-creating an identical rule returns 200 with the existing route.

```ts
openemail.routes.create(
  body: RoutesCreateBody,
  options?: CallOptions,
): ApiPromise<Route>
```

It calls `POST /routes`: [Create a routing rule](/docs/api/routing/post_RouteCreate) in the API reference.

## Example

```ts
const route = await openemail.routes.create({ address: 'ada@example.com', destinationType: 'mailbox' })
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `body` | [`RoutesCreateBody`](#routescreatebody) | 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, or D2: the route's own address must be an ASCII local part on an A-label domain), unknown_domain, domain_is_alias, unknown_mailbox (missing, inaccessible, or outside the route domain's account, including platform domains), webhook_format_unavailable (reference format asked for on a deployment that mints no capability URLs), or destination_is_self / destination_loops / destination_chain_too_long when the forward target routes back to this address |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | address_blocked — the address, its tag-stripped form, or its domain is on the platform blocklist (migration 0070) |
| `409` | route_exists — the address is bound to a DIFFERENT destination; mailbox_is_group_persona — the mailbox target is a group's persona, which nothing may route to; group_delete_in_flight — this group's delete is still running (retry the DELETE, then re-create); inbound_edge_cap — the destination cannot accept another incoming edge; route_changed — a concurrent edit replaced the publication |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `429` | rate_limited — the account's daily address or mailbox creation limit (a group also mints its persona) |
| `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 (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

### RoutesCreateBody

```ts
/** The body of `routes.create`. */
type RoutesCreateBody = {
  address: string
  destinationType: ('mailbox' | 'webhook' | 'remote' | 'group')
  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.
   * @default false
   */
  paced?: boolean
  posting?: ('open' | 'members')
  remoteAddress?: string
  webhookFormat?: ('parsed' | 'reference')
  webhookSecret?: string
  webhookUrl?: string
}
```

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