# Update an exact-address route

`PUT /api/domains/{id}/routes/{routeId}`

Replaces the route's local part and endpoint for future accepted mail. UTF-8 local parts (at most 64 UTF-8 bytes) are trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Previously accepted messages retain their pinned route and endpoint revisions.

Send API requests to your Wildmail application origin. The documentation host does not serve API requests.

## Authentication

- apiKey: Send `Authorization: Bearer <token>` in the request headers. Wildmail scoped kmx_ API token.

- session: Send the credential in the cookie named `better-auth.session_token`. Browser session cookie used by the hosted app. It may use the __Secure- cookie prefix. Use the auth client to manage cookies.

Each bullet above is an alternative authentication method.

Required API key scope: `domains:write`.

Audience: management.

## Parameters

### id

path parameter; required.

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

### routeId

path parameter; required.

```json
{
  "name": "routeId",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string",
    "format": "uuid"
  }
}
```

## Request body

Required.

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "localPart": {
      "type": "string",
      "maxLength": 64,
      "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Plus-tags are preserved literally and are not stripped. Patterns are not supported."
    },
    "endpointId": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "localPart",
    "endpointId"
  ]
}
```

Example:

```json
{
  "localPart": "orders+acme",
  "endpointId": "11111111-1111-4111-8111-111111111111"
}
```

## Responses

### 200

Updated

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "route": {
      "$ref": "#/components/schemas/DomainRoute"
    }
  },
  "required": [
    "route"
  ]
}
```

### 400

Invalid local part or endpoint identifier.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 401

Missing, invalid or revoked credentials.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 403

Required scope or account access missing.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 404

Domain, route or endpoint not found in this account.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 409

The local part is already routed on this domain.

Content type: `application/json`.

Schema:

```json
{
  "$ref": "#/components/schemas/Error"
}
```

### 429



### 503



## Referenced schemas

References resolve against the [OpenAPI specification](/openapi.json).

### #/components/schemas/DomainRoute

```json
{
  "type": "object",
  "description": "An exact local-part route on one customer-owned custom domain. Status reflects whether the account plan and domain allow the route. endpointStatus reports the current endpoint state.",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "domainId": {
      "type": "string",
      "format": "uuid"
    },
    "localPart": {
      "type": "string",
      "maxLength": 64,
      "description": "Valid UTF-8 email local part, at most 64 UTF-8 bytes. Trimmed, Unicode-normalized, and lowercased before matching. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped."
    },
    "endpointId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Null when the selected endpoint was deleted. The stored exact route still blocks catch-all fallback until deleted or updated."
    },
    "endpointName": {
      "type": [
        "string",
        "null"
      ]
    },
    "endpointStatus": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "active",
        "paused",
        "failing",
        null
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "suspended"
      ],
      "description": "Free plan downgrades suspend stored routes. A suspended exact match is rejected during SMTP admission and does not use the catch-all."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": [
    "id",
    "domainId",
    "localPart",
    "endpointId",
    "endpointName",
    "endpointStatus",
    "status",
    "createdAt",
    "updatedAt"
  ]
}
```

### #/components/schemas/Error

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": [
    "error"
  ]
}
```
