Manage Identities

Agent identities are the unit of presence on Inkbox. Each identity owns exactly one mailbox and one tunnel; you can optionally attach a phone number and vault-secret access. Handles are globally unique across all Inkbox customers and are normalized — a leading @ is automatically stripped, so @my-agent and my-agent are equivalent.

POST /identities

Atomically provisions the identity, its mailbox, and its tunnel in a single transaction. You can optionally provision and link a phone number, and attach access to existing vault secrets in the same request. The mailbox and tunnel are always created; the nested mailbox and tunnel bodies only customize them.

Request body

mailbox fields

Sending-domain resolution. Omitting mailbox does not necessarily yield {agent_handle}@inkboxmail.com. The server resolves the sending domain in three cases: if the org has set a verified custom domain as its default, omitting the body lands the mailbox on that custom domain with a server-chosen local part; passing "sending_domain": null forces the platform domain and the local part to agent_handle; passing an explicit bare-domain string pins the mailbox to that verified custom domain (404 if the domain isn't verified for your org).

tunnel fields

The tunnel name is always forced to agent_handle; the public hostname is e.g. my-agent.inkboxwire.com.

phone_number fields

vault_secret_ids

Use this to attach existing vault secret access to the new identity. The organization must already have an active vault. If omitted, no vault secret access is attached.

Accepted forms:

• A single stringified UUID to attach one secret
• A list of UUIDs to attach specific secrets
• "all" or "*" to attach all active secrets in the active vault

Request example

JSON

Response (201)

Returns the full identity-detail shape with nested mailbox and tunnel objects always populated; phone_number is populated when one was provisioned.

JSON

mailbox and tunnel are always populated for active customer identities; only phone_number is optional. If vault_secret_ids is omitted, no vault secret access is attached.

Mailbox local-part validation

When you provide mailbox.email_local_part, it must satisfy these rules:

• Length: 3–64 characters
• Characters: lowercase letters, numbers, hyphens (-), underscores (_), and dots (.)
• Start/end: must begin and end with a letter or number
• No consecutive dots: my..agent is rejected
• No @: provide the handle only, not a full email address
• Reserved names blocked: some system addresses are reserved; you'll get a 409 if you pick one.

Handle validation

Handles are globally unique across all Inkbox customers. They must satisfy:

• Length: 3–63 characters
• Characters: lowercase letters (a-z), digits (0-9), and hyphens (-)
• Start/end: must begin and end with a letter or digit
• No consecutive hyphens

Some handles are reserved; you'll get a 409 if you pick one.

Error responses

The 409 body uses a stable error envelope:

JSON

blocking_namespace is a programmatic discriminator with three possible values — "identities", "tunnels", or "mail" — indicating which resource produced the conflict.

Code examples

cURL

cURL

JavaScript

Python

GET /identities

List all identities for your organization, newest first. Returns the flat identity object — nested mailbox / tunnel / phone_number blocks are not included on list. Use Get identity to fetch the detail shape.

Each identity carries its access rules, so you can see who can view it without a follow-up call. Agent-scoped API keys get a narrowed list — only their own identity plus identities granted to them — and an empty access array.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /identities/{agent_handle}

Get a single identity with its linked communication channels. Returns the identity-detail shape with nested mailbox, tunnel, and (when attached) phone_number objects.

With an agent-scoped API key, only the caller's own identity and identities granted to it via agent visibility are reachable; any other handle returns 404.

Path parameters

Response (200)

JSON

mailbox and tunnel are always populated for active customer identities. phone_number is null when no phone number is attached.

Error responses

Code examples

cURL

cURL

JavaScript

Python

PATCH /identities/{agent_handle}

Update an identity's handle, display name, description, iMessage settings, or status. Returns the flat identity object — nested mailbox, tunnel, and phone_number blocks are not included on PATCH responses; use Get identity to fetch the detail shape.

Path parameters

Request body

PATCH semantics

The server distinguishes three caller intents on display_name and description:

agent_handle, status, imessage_enabled, and imessage_filter_mode accept only the omit half — sending null for those fields is not a clear operation.

Request example

JSON

Response (200)

JSON

Error responses

The 409 body for a taken handle uses the same envelope as create: { code: "agent_handle_taken", message, blocking_namespace }. The 409 for a platform-domain rename returns a flat { detail: "Cannot rename agent_handle: ..." } body explaining that the handle is the mailbox name on the platform domain.

Code examples

cURL

cURL

JavaScript

Python

DELETE /identities/{agent_handle}

Delete an identity. The linked mailbox and tunnel are deleted as part of the cascade. Any identity-scoped API keys tied to this identity are revoked. Any linked phone number is released back to the carrier as part of the cascade — phone numbers cannot exist without an identity. The handle becomes available for reuse immediately. Returns 204 No Content on success.

If the carrier release fails, the entire delete is aborted with a 502 and the identity stays active so you can retry safely.

Path parameters

Error responses

Code examples

cURL

cURL

JavaScript

Python

Extends the identity object with linked channel data. Returned by the create endpoint and the get endpoint.