---
title: "Your instant inbox (<account code>.oveyon.app): address, mailboxes, state"
method: GET
path: "/inbound/instant"
tags: ["Inbound"]
---

# Your instant inbox (<account code>.oveyon.app): address, mailboxes, state

`GET /inbound/instant`

## Request

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

Read-only: never switches anything on. An account that never switched it on sees the domain it WILL have, with `active: false`. Receiving works on every plan; sending from it (replies included) only on paid plans (`sending`). While the instant inbox is not enabled on the platform this route answers 404 not_found, like a route that does not exist. Scope read:inbound.

## Response `200`

State

- InstantInbox: The instant inbox of the account: `<account code>.oveyon.app`, with no DNS on your side. Its mailboxes are ordinary mailboxes — manage them later with PATCH/DELETE /v1/inbound/routes/{id}.
  - `domain` string, nullable: `<code>.oveyon.app` — the account short code. null when the account cannot have one (see `available`).
  - `available` boolean: false = this account cannot have an instant inbox (no short code, or the account is not active).
  - `active` boolean: Whether the account switched it on (POST /v1/inbound/instant). Until then nothing is received there.
  - `catchAll` 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
  - `mailboxes` InboundRoute[]: Named mailboxes `<agent>@<code>.oveyon.app`, each with its own thread, channels and policies.
    - `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
  - `sending` object: Sending FROM the instant inbox (replies included) is for paid plans only.
    - `allowed` boolean
    - `reason` 'managed_domain_requires_paid_plan' | 'null', nullable
  - `limits` object
    - `perHour` integer: Messages per hour the account receives on its instant inbox. Above it the MX answers 450 4.2.1 and the sender retries in the next hour.
    - `thisHour` integer, nullable: Received in the current hour (null when it cannot be read right now).
    - `retentionDays` integer: How long received messages are kept: on the free plan, the plan retention; on paid plans, the same as your own domains.
  - `url` string

## Other responses

- `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
- `429`: Per-key limit (`rate_limited`, 600 requests/min by default per API key — or per MCP OAuth connection —, from any IP), per-IP limit for requests WITHOUT a valid credential (`rate_limited`, 600/min by default), too many unknown or malformed credentials from your address (`too_many_auth_failures`, 20/min by default, counted per IPv4 address or per IPv6 /48; a missing `Authorization`, an expired OAuth token or a disabled key do not count, and anything without the shape of one of our keys counts without being checked; from an address over that limit a valid key still gets through within 120 credential checks/min, and above them every credential not validated in the last 5 minutes gets this 429 until the minute turns) — all checked before the route, on every operation —, account quota (`quota_exceeded` with `window`, `used`, `limit`), warmup cap (`warmup_cap_reached`) or saturation (`queue_full`). Honor `Retry-After` with exponential backoff and jitter.
- `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)