---
title: "Switch the instant inbox on, or create a named mailbox on it (<agent>@<code>.oveyon.app)"
method: POST
path: "/inbound/instant"
tags: ["Inbound"]
---

# Switch the instant inbox on, or create a named mailbox on it (<agent>@<code>.oveyon.app)

`POST /inbound/instant`

## Request

- Base URL: `https://api.oveyon.com/v1`
- URL: `https://api.oveyon.com/v1/inbound/instant`
- Auth: HTTP bearer

No DNS on your side: the domain is ours. Without `localPart` it switches the account inbox on — its domain and the catch-all `*@<code>.oveyon.app` — and returns the catch-all (201 the first time, 200 after: idempotent). With `localPart` it creates a named mailbox with its own channels and policies (201), like POST /v1/inbound/routes — the same limits (200 mailboxes per domain, 1000 per account), the same inline webhook (secret shown once), born without security choices. Received mail counts like any inbound mail; above the per-hour limit the MX answers 450 4.2.1 and the sender retries. Sending FROM it is for paid plans only: on the free plan /v1/send and /v1/inbound/{uid}/reply answer 422 managed_domain_requires_paid_plan (SMTP: 550 5.7.1). Forwarding from it follows the forwarding rules of every mailbox (verified destinations only). While the instant inbox is not enabled on the platform this route answers 404 not_found. Scope write:inbound.

## Request body

- InstantInboxCreate: Without `localPart`: switches the instant inbox on (its domain and catch-all) and returns the catch-all. With `localPart`: creates the named mailbox `<localPart>@<code>.oveyon.app` (switching the inbox on first if needed).
  - `localPart` string: The part before the @ (lower-cased). Letters, digits and . _ % + - (no @).
  - `active` boolean
  - `channels` object[]: Only with `localPart`. Same shape as POST /v1/inbound/routes: `{ type: "webhook", url, mode? }` for a NEW webhook (at most one; the secret is returned once) or `{ channelId, mode? }` for an existing channel of the instant domain.
    - `channelId` integer
    - `type` 'webhook'
    - `url` string, uri
    - `mode` 'full+attachments' | 'full' | 'summary'

## Response `200`

Already on — the catch-all as it is

- InboundRoute
  - `id` integer
  - `domain` string
  - `address` string: `local@domain`, or `*@domain` for a catch-all.
  - `matchType` 'exact' | 'catchall'
  - `localPart` string, nullable
  - `active` boolean
  - `inboundEnabled` boolean: Whether inbound is switched on for the DOMAIN (portal). A mailbox on a domain with inbound off does not receive yet.
  - `agentSafetyMode` string, nullable: null = the mailbox delivers everything with the verdict (default for API-created mailboxes); `dangerous` = holds dangerous messages (set in the portal).
  - `retroScan` boolean
  - `spamFilter` boolean: The mailbox spam filter is on (opt-in; false on every new mailbox). See `spamFilter` on received messages.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time, nullable
  - `createdBy` string, nullable: `api:<key prefix>`, `portal:<user>`, `wizard:<user>`, `admin:<operator>`; null = before this was recorded.
  - `channelCount` integer: List only: active channels attached.
  - `channels` InboundRouteChannel[]: Detail only.
    - `assocId` integer: The attachment id — use it in DELETE /v1/inbound/routes/{id}/channels/{assocId}.
    - `channelId` integer
    - `type` 'webhook' | 'telegram' | 'slack' | 'forward'
    - `label` string, nullable
    - `destination` string, nullable: Webhook URL, forward address, Telegram chat or Slack channel.
    - `mode` 'full+attachments' | 'full' | 'summary' | 'null', nullable
    - `active` boolean
    - `broken` boolean: The channel is marked broken (deliveries failing) — see the panel.
  - `url` string

## Other responses

- `201`: Switched on (the catch-all) or the named mailbox created — an inline webhook secret is shown once
- `400`: Invalid request — fix it before retrying. Includes `invalid_json`: with `Content-Type: application/json` the body must be valid JSON and cannot be empty; and `request_too_complex` (with `limit`): the body has a list of more than 10,000 items, more than 60,000 values in total, more than 64 levels of nesting or a number/literal longer than 32 characters — text does not count, so a large attachment is one value. An address outside ASCII (accents, a full-width @, a control character, an international domain not in xn-- form) is refused here with `reason: address_not_ascii` and the `field` it came in (`error` stays the family of that field: `bad_recipient` for to/cc/bcc, `invalid_email` for contacts, `bad_request` otherwise).
- `401`: Missing or invalid API key.
- `403`: Insufficient scope (`insufficient_scope`, with `required` and `have`), a scope the key holds but cannot use while its human-approval lock is on (`scope_blocked_by_approval_lock`, with `required` — approve:holds, write:send-policies, manage:webhooks, write:inbound, write:templates, write:surveys, write:domains, write:contacts), API key switched off by its owner in the panel (`key_disabled` — the key is valid; turn it back on or use another one, do not rotate), sending disabled, account suspended (`account_suspended`) or unknown (`account_unknown`), or the key used from an IP outside its allowed ranges (`ip_not_allowed`, with the `allowed` list — see /v1/credentials/ip-rules). 403 is not a limit: do not retry.
- `404`: not_found (the instant inbox is not enabled on the platform), or channel_not_found
- `409`: route_exists (that mailbox already exists), instant_inbox_unavailable (no short code, or the account is not active), instant_inbox_conflict (the address is taken by an older registration — contact support)
- `413`: payload_too_large — the request body exceeds this route's limit (`limit`, in bytes: 25 MB unless the operation says otherwise). The key is validated before the body is read: without a valid key the answer is 401/403 and the body is not read. Do not retry the same body.
- `415`: unsupported_media_type — send the body as `application/json` (form and plain-text bodies are not accepted).
- `422`: route_limit_domain, route_limit_tenant
- `429`: rate_limited — switching the instant inbox back on after you switched its receiving off waits like the switch on the domain page: at most one switch-on every 5 s per domain and 20 per minute per account (switching off never waits). Nothing changed: receiving stays off; honor `Retry-After` (seconds, also in `retryAfter`) and call again. Or the per-key inbound write limit (`Retry-After: 60`), or any of the common limits.
- `500`: internal_error — an unexpected failure on our side. The detail stays in our logs, never in the body. Retry reads; retry a write only when it is idempotent or carries an idempotency key.
- `503`: ip_rules_unavailable — the IP ranges bound to your key could not be checked right now (caution, not a denial). Retry after `Retry-After` (30 s).

---

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