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.

Mailboxes can be created either with the standalone endpoint below or via the optional nested mailbox payload when you create an identity.

Create mailbox POST

POST /mailboxes

Provision a new mailbox and link it to an existing identity. By default, the server generates a random unique email address. You can optionally request a specific email_local_part.

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"`.
`email_local_part`	string	No	Requested mailbox local part before `@inkboxmail.com`. If omitted, the server generates one.

Request example

JSON

Response (201)

JSON

Error responses

Status	Description
403	Organization ID missing from token
404	Agent identity not found
409	Identity already has a mailbox, or the requested email address is already taken
503	Unique email generation or final insert collided; retry the request

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. After deletion, the mailbox no longer receives inbound mail. 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. `sales.team@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)