---
title: "Create a recipient route"
method: POST
path: "/routes"
tags: ["Routes"]
---

# Create a recipient route

`POST /routes`

Binds a recipient pattern to a destination. Provide exactly one of
`endpoint_id` (an existing endpoint) or `function_id`. With `function_id`,
a dedicated route-target endpoint is minted for that function in the same
transaction, enabling per-address function routing (e.g.
`alice@acme.com -> functionA`).

## Headers

- `Idempotency-Key` string

## Request body

- object — Provide exactly one of `endpoint_id` or `function_id`. With `function_id`, a route-target endpoint is minted for that function and the route is bound to it in one transaction.
  - `match_type` 'exact' | 'wildcard' | 'regex', required
  - `pattern` string, required
  - `endpoint_id` string, uuid — An existing endpoint to route to. Mutually exclusive with function_id.
  - `function_id` string, uuid — Route to this function, minting its route-target endpoint if needed. Mutually exclusive with endpoint_id.
  - `domain_id` string, uuid, nullable — Scope the route to a domain; defaults to the pattern's domain.
  - `priority` integer
  - `enabled` boolean

## Response `201`

Route created

- object
  - `success` true, required
  - `data` object, required — A recipient routing rule binding an address pattern to one endpoint.
    - `id` string, uuid, required
    - `org_id` string, uuid
    - `domain_id` string, uuid, nullable — Domain the route is scoped to; null = org-wide.
    - `match_type` 'exact' | 'wildcard' | 'regex'
    - `pattern` string — The recipient address pattern (an exact address or a wildcard).
    - `pattern_norm` string, nullable — Normalized pattern used for matching.
    - `endpoint_id` string, uuid — The endpoint inbound mail matching this rule is delivered to.
    - `priority` integer — Evaluation order within a scope; lower is checked first.
    - `enabled` boolean
    - `match_count` string — How many emails have matched this rule (a bigint, returned as a string).
    - `last_matched_at` string, date-time, nullable
    - `created_at` string, date-time

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `403` — Authenticated caller lacks permission for the operation
- `409` — The request conflicts with the current state of the resource

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) · [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/primitive/primitive-api/revisions/c2299d28022c/schema)