# Create an exact-address route

`POST /api/domains/{id}/routes`

Creates an exact local-part route to an endpoint in this account. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. The maximum is 64 UTF-8 bytes. Free has an allowance of zero and returns 409 route_limit_reached. Recognized non-Free plans have unlimited exact routes. Route status is suspended while the effective plan disallows routes. Stored suspended routes remain counted. Hosted test addresses are managed separately.

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"
  }
}
```

## 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

### 201

Created

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 or endpoint not found in this account.

Content type: `application/json`.

Schema:

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

### 409

Exact route already exists or the account allowance is exhausted. For Free, code is route_limit_reached and limit is 0.

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"
  ]
}
```
