Receiving Routes API

Create, list, update, retrieve, and delete receiving routes for verified receiving domains.

Routes are tenant-scoped. API key callers need a full-access key that belongs to the domain owner. Dashboard session callers use the same /api/receiving/routes endpoints from the Receiving page.

Route object

json

{
  "object": "receiving_route",
  "id": "22222222-2222-4222-8222-222222222222",
  "domain_id": "11111111-1111-4111-8111-111111111111",
  "domain": "inbound.example.com",
  "type": "alias",
  "local_part": "help",
  "target_local_part": "support",
  "target_address": "support@inbound.example.com",
  "created_at": "2026-05-28T00:00:00.000Z",
  "updated_at": "2026-05-28T00:00:00.000Z"
}

type is one of exact, alias, or catch_all. catch_all routes use local_part: null and require target_local_part.

List routes

GET /api/receiving/routes

Optional query parameter:

Name	Type	Description
`domain_id`	UUID	Limit results to one owned domain. Cross-tenant domains return `404`.

Response:

json

{
  "object": "list",
  "data": []
}

Create a route

POST /api/receiving/routes

json

{
  "domain_id": "11111111-1111-4111-8111-111111111111",
  "type": "alias",
  "local_part": "help",
  "target_local_part": "support"
}

Creation requires a verified domain with receiving enabled. Exact routes may omit target_local_part; OpenSend then uses the exact local part as the target. Alias and catch-all routes require target_local_part.

Retrieve a route

GET /api/receiving/routes/{id}

Missing and cross-tenant route IDs both return 404.

Update a route

PATCH /api/receiving/routes/{id}

json

{
  "target_local_part": "inbox"
}

You can update local_part and target_local_part. Route type and domain are immutable; create a new route when those need to change.

Delete a route

DELETE /api/receiving/routes/{id}

Response:

json

{
  "object": "receiving_route",
  "id": "22222222-2222-4222-8222-222222222222",
  "deleted": true
}

Matching behavior

Inbound workers should resolve route decisions before inserting or updating received email rows. Precedence is exact address, then alias, then catch-all, then unrouteable. Store the resulting route_decisions array on received_emails so later detail views, logs, and webhook processors can audit the routing choice.