Jump to

Mailboxes

Mailboxes are the email addresses your agents send and receive mail from. Each mailbox belongs to an organization and gets a unique address on the Inkbox sending domain.

Create mailbox POST

POST /mailboxes

Provision a new mailbox. The email address is auto-generated by the server.

Request body

Field	Type	Required	Description
`agent_handle`	string	Yes	Agent identity handle to assign this mailbox to (e.g. `"sales-agent"` or `"@sales-agent"`). Leading `@` is stripped.
`display_name`	string	No	Human-readable name shown as the sender. Max 255 chars. Defaults to `"Inkbox User"`.

Request example

JSON

Response (201)

JSON

Error responses

Status	Description
403	Organization ID missing from token

Code examples

List mailboxes GET

GET /mailboxes

List all active mailboxes for your organization, newest first.

Response (200)

JSON

Code examples

Get mailbox GET

GET /mailboxes/{email_address}

Get a single mailbox by its email address.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox (local part or full address)

Response (200)

JSON

Code examples

Update mailbox PATCH

PATCH /mailboxes/{email_address}

Update mutable fields on a mailbox. Only supplied fields are modified.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox (local part or full address)

Request body

Field	Type	Required	Description
`display_name`	string	No	Human-readable name shown as the sender. Max 255 chars.
`webhook_url`	string \| null	No	HTTPS URL for webhook event delivery. Set to `null` to unsubscribe. See Webhooks.

Request example

JSON

Response (200)

Returns the updated mailbox object.

Code examples

Delete mailbox DELETE

DELETE /mailboxes/{email_address}

Delete a mailbox. The mailbox and its data are retained in storage but hidden from API responses and excluded from inbound mail delivery. Returns 204 No Content on success.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox (local part or full address)

Code examples

Mailbox object

Field	Type	Description
`id`	UUID	Unique mailbox identifier
`email_address`	string	Full email address (e.g. `agent-sales@inkboxmail.com`)
`display_name`	string \| null	Human-readable sender name
`webhook_url`	string \| null	HTTPS URL for webhook event delivery, or `null` if not configured
`status`	string	Lifecycle status: `active`, `paused`, `deleted`
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)