---
title: "Simulate routing for a recipient"
method: POST
path: "/routes/simulate"
tags: ["Routes"]
---

# Simulate routing for a recipient

`POST /routes/simulate`

Resolves where an inbound email to `recipient` would be delivered, with a
trace of every rule evaluated and why. Read-only; creates nothing.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `recipient` string, required
  - `event_type` string — Event type to model; defaults to email.received.

## Response `200`

Routing decision

- object
  - `success` true, required
  - `data` object, required — Where an inbound email to the recipient would be delivered, and why.
    - `outcome` 'matched' | 'defaulted' | 'none', required
    - `recipient` string, required
    - `endpoint_id` string, nullable, required
    - `matched_route_id` string, nullable, required
    - `matched_tier` 'exact' | 'wildcard' | 'regex' | 'null', nullable, required
    - `matched_pattern` string, nullable, required
    - `default_scope` 'domain' | 'org' | 'null', nullable, required
    - `evaluated` object[], required
      - `route_id` string, required
      - `tier` 'exact' | 'wildcard' | 'regex', required
      - `pattern` string, required
      - `result` 'hit' | 'miss' | 'skipped' | 'error', required
      - `reason` string
    - `truncated` boolean, required

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key

---

[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)