---
title: "Read the workspace inbound-mail address"
method: GET
path: "/account/inbox"
tags: ["Account"]
---

# Read the workspace inbound-mail address

`GET /account/inbox`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/account/inbox`
- Auth: HTTP bearer

The inbound-mail address of the workspace this credential is bound to, and whether mail sent to it is actually routed.

This is half of the agent control plane: an agent that wants documents to arrive by email reads this endpoint to learn the address to publish, and reads `status` to learn whether publishing it is worth anything.

Reading deliberately does not provision. The dashboard mints an address on demand; this endpoint never does, because an agent polling it would otherwise create a live inbound attack surface for a workspace that never asked for one. A workspace without an inbox answers `status: "not_provisioned"` and `address: null`; ask a human to open the inbox page once to create it.

`status` has three values and they are not interchangeable:

- `active`: an address exists and this deployment routes inbound mail to it.
- `not_provisioned`: inbound mail is configured, but this workspace has no address yet.
- `unavailable`: the deployment has no inbound mail domain configured. This outranks the other two: an address could still be formatted, but nothing would ever be delivered to it, so a caller that only checked for a non-null address would wait forever for mail that never routes.

The address format is `inkseal-<10 lowercase alphanumerics>@<inbound domain>`. Resolution of incoming mail is full-address only, so the domain matters as much as the local part.

## Response `200`

The workspace's inbox address and its delivery status.

- object
  - `data` AccountInbox, required: The workspace's inbound-mail address and whether this deployment routes mail to it.
    - `status` 'active' | 'not_provisioned' | 'unavailable', required: `active`: an address exists and mail routes to it. `not_provisioned`: inbound mail works but this workspace has no address yet; a human must create one from the dashboard. `unavailable`: this deployment routes no inbound mail at all, so any address would be inert.
    - `address` string, email, nullable, required: The full address to send documents to, or null when the workspace has no inbox. Mail is matched on the complete address, local part and domain both.
    - `inboundMailConfigured` boolean, required: Whether this deployment has an inbound mail domain configured. False means nothing sent to the address will ever arrive.

## Other responses

- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested).
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

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