---
title: "Update an inbound route"
method: PATCH
path: "/v1/email/inbound-routes/{route_id}"
tags: ["email-inbound-routes"]
---

# Update an inbound route

`PATCH /v1/email/inbound-routes/{route_id}`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/inbound-routes/{route_id}`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Updates an inbound route. Omitted fields are unchanged. The `domain` is immutable. Fields that depend on each other are checked against the updated route, so a change that leaves it inconsistent (for example `deliver_to_mailbox` without a target mailbox) returns `422`. Disabled routes are kept but skipped during evaluation.

## Headers

- `Idempotency-Key` string
- `X-Workspace-Id` string
- `X-Organization-Id` string

## Request body

- InboundRouteUpdate: Fields to update on an inbound route. Omitted fields are unchanged. The domain is immutable.
  - `match_type` 'address' | 'catch_all': How the route matches recipients.
  - `match_value` string, nullable: The local part an `address` route matches. `null` for `catch_all` routes.
  - `action` 'deliver_to_mailbox' | 'drop': What happens to matching mail. `deliver_to_mailbox` delivers it to `target_mailbox_id` (required). `drop` discards it silently, with nothing stored and no webhook fired.
  - `target_mailbox_id` string
  - `priority` integer: The order routes are tried in, lowest number first. Your own routes take a priority from 11 to 1000. The mailbox's own address always matches at priority 10.
  - `enabled` boolean: Whether the route is evaluated.

## Response `200`

Inbound route updated.

- InboundRoute: A routing rule that directs inbound mail on one of your domains into a mailbox, or drops it. Routes are tried in priority order, lowest number first. Each mailbox's own address always matches at priority 10 and your own routes take a priority from 11 to 1000, so delivery to an exact address always takes precedence.
  - `id` string, required
  - `domain` string, required: The domain the route applies to.
  - `match_type` 'address' | 'catch_all', required: How the route matches recipients. `address` matches one local part. `catch_all` matches every recipient on the domain that nothing else matched.
  - `match_value` string, nullable, required: The local part an `address` route matches. `null` for `catch_all` routes.
  - `action` 'deliver_to_mailbox' | 'drop', required: What happens to matching mail. `deliver_to_mailbox` delivers it to `target_mailbox_id`. `drop` discards it silently, with nothing stored and no webhook fired.
  - `target_mailbox_id` string, required
  - `priority` integer, required: The order routes are tried in, lowest number first. Your own routes take a priority from 11 to 1000, and default to 100. A mailbox's own address always matches at priority 10.
  - `enabled` boolean, required: Whether the route is evaluated. Disabled routes are kept but skipped.
  - `created_at` string, date-time, required: When the route was created.
  - `updated_at` string, date-time, required: When the route was last updated.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/3e2a50466454?raw)