Mailboxes

Mailboxes are the email addresses your agents send and receive mail from. Each mailbox is owned 1:1 by an agent identity — mailboxes are created and destroyed atomically with the identity. To provision a mailbox, create an identity; to remove one, delete the identity. This page covers the read and update surface on the mailbox itself.

List mailboxes

GET /mailboxes

List all active mailboxes for your organization, newest first.

Query parameters

Parameter	Type	Description
`limit`	integer	Maximum rows to return (1–101). Omit to return all visible mailboxes.
`offset`	integer	Rows to skip (0–10,000). Defaults to `0`.

Response (200)

JSON

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email_address": "sales-agent@inkboxmail.com",
    "sending_domain": "inkboxmail.com",
    "agent_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "signature_html": null,
    "signature_text": null,
    "signature_enabled": false,
    "storage_used_bytes": 184320,
    "storage_limit_bytes": 2147483648,
    "created_at": "2025-03-01T12:00:00Z",
    "updated_at": "2025-03-01T12:00:00Z"
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "email_address": "support-bot@inkboxmail.com",
    "sending_domain": "inkboxmail.com",
    "agent_identity_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "signature_html": null,
    "signature_text": null,
    "signature_enabled": false,
    "storage_used_bytes": 5242880,
    "storage_limit_bytes": 2147483648,
    "created_at": "2025-02-15T09:30:00Z",
    "updated_at": "2025-02-15T09:30:00Z"
  }
]

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch("https://inkbox.ai/api/v1/mail/mailboxes", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const mailboxes = await response.json();

import requests

response = requests.get(
    "https://inkbox.ai/api/v1/mail/mailboxes",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
mailboxes = response.json()

Get mailbox

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

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email_address": "sales-agent@inkboxmail.com",
  "sending_domain": "inkboxmail.com",
  "agent_identity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "signature_html": null,
  "signature_text": null,
  "signature_enabled": false,
  "storage_used_bytes": 184320,
  "storage_limit_bytes": 2147483648,
  "created_at": "2025-03-01T12:00:00Z",
  "updated_at": "2025-03-01T12:00:00Z"
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/sales-agent@inkboxmail.com" \
  -H "X-API-Key: YOUR_API_KEY"

const emailAddress = "sales-agent@inkboxmail.com";
const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const mailbox = await response.json();

import requests

email_address = "sales-agent@inkboxmail.com"
response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
mailbox = response.json()

Update mailbox

PATCH /mailboxes/{email_address}

The path selects the existing mailbox. Its email address, local part, and sending domain cannot be changed through PATCH. Supplying address fields returns 422. On inkboxmail.com, the local part is fixed with the agent handle. Configure the mailbox’s custom signature. Custom signatures are available on paid plans. Use an admin API key or a claimed agent’s key for its own mailbox. The legacy filter_mode field is deprecated but still accepted as a compatibility bridge to the owning identity’s mail_filter_mode. New integrations should set that control on the identity instead. Writing this shared field sets both email directions and removes directional customization, even if its previous value is unchanged. Reading it returns the common effective mode when both directions agree, otherwise the last shared baseline. Use the identity’s mail_inbound_filter_mode and mail_outbound_filter_mode for effective directional settings. See directional filter modes.

Path parameters

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

Filter mode is moving. The canonical control now lives on the agent identity as mail_filter_mode — see Manage identities. Set it with PATCH /identities/{agent_handle}; it interprets the mail contact rules. Sending filter_mode on this mailbox PATCH is deprecated but still accepted and forwards to the identity’s mail_filter_mode.

display_name has moved. Display name is now an identity-level field; this endpoint rejects display_name with 422 and a redirect-style message pointing at PATCH /identities/{agent_handle}.

Webhook configuration has moved. Mail event delivery is configured via the Webhook Subscriptions API, not on the mailbox resource.

Request body

Field	Type	Description
`signature_html`	string \| null	HTML fragment, up to 16,384 characters. Inkbox normalizes formatting before saving. `null` or an empty string clears it.
`signature_text`	string \| null	Plain-text equivalent, up to 16,384 characters. `null` or an empty string clears it.
`signature_enabled`	boolean	Automatically insert the saved signature. Defaults to `false` on new mailboxes. `null` is invalid.
`filter_mode`	string	Deprecated; use the identity’s `mail_filter_mode`. Requires an admin API key.

Omitted fields stay unchanged, with one exception: supplying signature_html without signature_text regenerates the text fallback, or clears it when HTML is cleared. Supply both fields to choose your own fallback. At send time, a null text value falls back to readable text from the saved HTML. To switch to text only, clear HTML and supply text in the same request. Whitespace-only strings also clear a field. Enabling an empty signature does not add anything. See Signature formats for HTML, image, and file-content guidance.

cURL

curl -X PATCH "https://inkbox.ai/api/v1/mail/mailboxes/agent%40inkboxmail.com" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signature_html": "<p><strong>Example Support</strong><br>example.com</p>",
    "signature_text": "Example Support\nexample.com",
    "signature_enabled": true
  }'

Response (200)

Returns the updated mailbox object, including the saved HTML and text. Use the returned values when displaying or editing the signature.

Errors

Status	Meaning
`402`	Custom signatures are unavailable for your organization. Saving nonempty content or enabling insertion requires access to the feature. You can still disable or clear a signature.
`422`	Invalid fields, a signature over the character limit, or `signature_enabled: null`.

Mailbox object

Field	Type	Description
`id`	UUID	Unique mailbox identifier
`email_address`	string	Full email address (e.g. `sales-agent@inkboxmail.com`)
`sending_domain`	string	Bare domain the mailbox sends from, derived from `email_address`. Either the platform default (`inkboxmail.com`) or a verified custom domain registered to your org.
`filter_mode`	string	Deprecated (`"whitelist"` or `"blacklist"`), mirroring the owning identity’s `mail_filter_mode`. Still accepted on the mailbox PATCH as a compatibility bridge that forwards to the identity’s mode; the canonical control is the identity’s `mail_filter_mode`, set via `PATCH /identities/{agent_handle}` — see Manage identities.
`agent_identity_id`	UUID \| null	Agent identity that owns this mailbox. Always populated for active customer mailboxes.
`inbound_filter_mode`, `outbound_filter_mode`	string	Non-null effective email receiving and sending modes: `whitelist` or `blacklist`. Configure these on the identity.
`notices`	array	Optional top-level response notices on object responses
`status`	string	Lifecycle status: `active` or `paused`
`storage_used_bytes`	integer	Bytes of mail currently stored in this mailbox. Always present.
`storage_limit_bytes`	integer \| null	Storage cap for this mailbox, in bytes (e.g. `2147483648` = 2 GiB). `null` when the route did not resolve a cap.
`signature_html`	string \| null	Saved HTML signature. Defaults to `null`.
`signature_text`	string \| null	Saved plain-text signature or generated fallback. Defaults to `null`.
`signature_enabled`	boolean	Saved automatic-insertion preference. Defaults to `false`; insertion also requires feature availability.
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Mailbox storage. Storage counts inbound and outbound mail plus associated storage overhead. Deleting a message or a thread frees its space immediately. Sizes are byte counts: 2147483648 bytes is 2 GiB. Caps vary by plan — see pricing.

Custom email signatures — setup, formats, and automatic insertion
Pricing — per-plan mailbox storage caps
Webhook Subscriptions — configure identity-owned mail-event delivery
Mail contact rules — the allow/block list interpreted by the identity’s mail_filter_mode
Email guide — Filtering inbound mail — whitelist/blacklist walkthrough

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

List mailboxes

Query parameters

Response (200)

Code examples

Get mailbox

Path parameters

Response (200)

Code examples

Update mailbox

Path parameters

Request body

Response (200)

Errors

Mailbox object

​List mailboxes

​Query parameters

​Response (200)

​Code examples

​Get mailbox

​Path parameters

​Response (200)

​Code examples

​Update mailbox

​Path parameters

​Request body

​Response (200)

​Errors

​Mailbox object

​Related

List mailboxes

Query parameters

Response (200)

Code examples

Get mailbox

Path parameters

Response (200)

Code examples

Update mailbox

Path parameters

Request body

Response (200)

Errors

Mailbox object

Related