---
title: "Create an inbound route"
method: POST
path: "/v1/email/inbound-routes"
tags: ["email-inbound-routes"]
---

# Create an inbound route

`POST /v1/email/inbound-routes`

## Request

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

Creates a routing rule that delivers matching inbound mail on one of your domains to a mailbox, or drops it. Routes are evaluated in order, lowest `priority` first, and a mailbox's own address always matches ahead of any route you create. Mail that no route matches is still received as a plain received email. The `domain` must be one of your workspace's inbound-enabled domains. Some fields depend on each other, and that dependency is described on the field itself. Breaking one of those rules returns `422`.

## Headers

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

## Request body

- InboundRouteCreate: Parameters for creating an inbound route.
  - `domain` string, required: The domain the route applies to. It has to be one of your inbound-enabled custom domains.
  - `match_type` 'address' | 'catch_all', required: How the route matches recipients. `address` matches one local part and requires `match_value`. `catch_all` matches every recipient on the domain that nothing else matched.
  - `match_value` string: The local part an `address` route matches. Required for `address` routes. Stored lowercase.
  - `action` 'deliver_to_mailbox' | 'drop', required: 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, so a route can never pre-empt exact-address delivery.
  - `enabled` boolean: Whether the route is evaluated.

## Response `201`

Inbound route created.

- 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/6dfce1179799?raw)