# List exact-address routes for a custom domain

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

Lists this domain's exact local-part routes and the account-wide route allowance. UTF-8 local parts are trimmed, Unicode-normalized, and lowercased before matching. Unicode domains use lowercase IDNA ASCII for lookup. Matching is case-insensitive. Plus-tags are preserved literally and are not stripped. Exact matches take precedence over the domain catch-all. A matching exact route can accept mail without a catch-all endpoint. Unmatched addresses are rejected if no catch-all is configured. A suspended exact route or one whose endpoint is unavailable is rejected during SMTP admission instead of falling through to catch-all.

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:read`.

Audience: management.

## Parameters

### id

path parameter; required.

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

## Responses

### 200

Success

Content type: `application/json`.

Schema:

```json
{
  "type": "object",
  "properties": {
    "routes": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/DomainRoute"
      }
    },
    "allowance": {
      "type": "object",
      "properties": {
        "used": {
          "type": "integer",
          "minimum": 0
        },
        "limit": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "planName": {
          "type": "string"
        }
      },
      "required": [
        "used",
        "limit",
        "planName"
      ]
    }
  },
  "required": [
    "routes",
    "allowance"
  ]
}
```

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

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