<Intro>

<EndpointHeader />

<Description>

Creates a routing rule that delivers matching inbound mail on one of your domains to a mailbox, or drops it. Routes are evaluated 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, and each field's cross-field requirements (see the field descriptions) return `422` when unmet.

</Description>

</Intro>

<Payload kind="request">

<Field name="domain" type="string" required>

<Description>

The domain the route applies to — one of your inbound-enabled custom domains.

</Description>

</Field>

<Field name="match_type" type="string" required>

<Description>

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.

</Description>

<Description>

Possible values: `address`, `catch_all`

</Description>

</Field>

<Field name="match_value" type="string">

<Description>

The local part an `address` route matches. Required for `address` routes; stored lowercase.

</Description>

</Field>

<Field name="action" type="string" required>

<Description>

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.

</Description>

<Description>

Possible values: `deliver_to_mailbox`, `drop`

</Description>

</Field>

<Field name="target_mailbox_id" type="string">

<Description>

The mailbox that receives matching mail. Required for `deliver_to_mailbox` routes.

</Description>

</Field>

<Field name="priority" type="integer">

<Description>

Evaluation order — lowest number wins. Explicit routes accept 11–1000; the mailbox's own address always matches at priority 10, so a route can never pre-empt exact-address delivery.

</Description>

</Field>

<Field name="enabled" type="boolean">

<Description>

Whether the route is evaluated.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

Inbound route ID.

</Description>

</Field>

<Field name="domain" type="string" required>

<Description>

The domain the route applies to.

</Description>

</Field>

<Field name="match_type" type="string" required>

<Description>

How the route matches recipients. `address` matches one local part; `catch_all` matches every recipient on the domain that nothing else matched.

</Description>

<Description>

Possible values: `address`, `catch_all`

</Description>

</Field>

<Field name="match_value" type="nullable string" required>

<Description>

The local part an `address` route matches. Null for `catch_all` routes.

</Description>

</Field>

<Field name="action" type="string" required>

<Description>

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.

</Description>

<Description>

Possible values: `deliver_to_mailbox`, `drop`

</Description>

</Field>

<Field name="target_mailbox_id" type="nullable string" required>

<Description>

The mailbox that receives matching mail. Null for `drop` routes.

</Description>

</Field>

<Field name="priority" type="integer" required>

<Description>

Evaluation order — lowest number wins. Explicit routes accept 11–1000 (default 100); the mailbox's own address always matches at priority 10.

</Description>

</Field>

<Field name="enabled" type="boolean" required>

<Description>

Whether the route is evaluated. Disabled routes are kept but skipped.

</Description>

</Field>

<Field name="created_at" type="string" required>

<Description>

When the route was created.

</Description>

</Field>

<Field name="updated_at" type="string" required>

<Description>

When the route was last updated.

</Description>

</Field>

</Payload>