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 /mailboxesProvision 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. |
filter_mode | string | No | "blacklist" (default) or "whitelist". Controls how contact rules are interpreted for this mailbox. Requires an admin API key or Clerk JWT to set. |
Request example
JSONResponse (201)
JSONError 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
cURLList mailboxes GET
GET /mailboxesList all active mailboxes for your organization, newest first.
Response (200)
JSONCode examples
cURLGet 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)
JSONCode examples
cURLUpdate 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. |
filter_mode | string | No | "blacklist" or "whitelist". Controls how contact rules are interpreted for this mailbox. Admin API key or Clerk JWT required to change this field. |
Request example
JSONResponse (200)
Returns the updated mailbox object. When this request changes filter_mode to a new value, the response also includes a filter_mode_change_notice object counting rules that are now redundant under the new mode (see the Mailbox object below). The field is null on any other PATCH and on GET, list, and create responses.
Code examples
cURLDelete 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
cURLMailbox 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 |
filter_mode | string | "blacklist" (default) or "whitelist". Decides how contact rules are interpreted for inbound mail. |
agent_identity_id | UUID | null | Agent identity that owns this mailbox, or null if the mailbox is standalone (not tied to any agent) |
status | string | Lifecycle status: active, paused, deleted |
created_at | string | Creation timestamp (ISO 8601) |
updated_at | string | Last update timestamp (ISO 8601) |
filter_mode_change_notice | object | null | Populated only on PATCH responses where filter_mode was actually changed. null otherwise. See shape below. |
filter_mode_change_notice
| Field | Type | Description |
|---|---|---|
new_filter_mode | string | The mode the mailbox was just flipped to ("whitelist" or "blacklist") |
redundant_rule_action | string | "block" when the new mode is whitelist; "allow" when the new mode is blacklist |
redundant_rule_count | integer | Number of active rules whose action equals redundant_rule_action. 0 is a clean flip; a value greater than 0 suggests the operator review or delete those rules. Paused and deleted rules are not counted. |
- Mailbox contact rules — the allow/block list interpreted by
filter_mode - Filtering guide — whitelist/blacklist walkthrough for mail and phone