Managing Mailboxes

Once a mailbox is connected, you can list your mailboxes, see per-mailbox message counts, update settings like the display name or a default template, pause polling, and delete a mailbox you no longer need.

List your mailboxes

curl "https://spideriq.ai/api/v1/mail/mailboxes" \
  -H "Authorization: Bearer $TOKEN"

Returns every mailbox for your workspace with its email_address, display_name, provider, is_active flag, and poll state — but never the stored passwords. From the CLI:

spideriq mail mailboxes --format yaml

See message counts

For an inbox sidebar or a quick health check, GET /mail/mailboxes/stats returns per-mailbox totals plus a workspace rollup:

curl "https://spideriq.ai/api/v1/mail/mailboxes/stats" \
  -H "Authorization: Bearer $TOKEN"
# → { "mailboxes": [ { "email": "...", "total": 812, "unread": 14, "starred": 3 } ],
#     "totals": { "total": 812, "unread": 14, "starred": 3, "mailbox_count": 1 } }

Update a mailbox

PATCH /mail/mailboxes/{email} updates the editable settings. You can change the display name, pause or resume polling with is_active, and attach a default template that is applied to every outgoing message.

curl -X PATCH "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alice Smith · Sales",
    "default_template_id": 42,
    "template_variables": { "sender_name": "Alice Smith", "title": "Sales Director" }
  }'

template_variables fills in the default template's placeholders. See Email Templates for how default templates work. Pass default_template_id: 0 to clear the default.

Tip: Set is_active to false to pause IMAP polling for a mailbox without deleting it — useful while rotating credentials or pausing an agent. The mailbox and its stored messages stay intact.

Pause polling

curl -X PATCH "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

While inactive, the poller skips the mailbox — no new inbound mail is ingested. Existing messages remain readable and you can still send.

Delete a mailbox

Deleting a mailbox removes it and all of its stored messages from SpiderMail. It does not touch anything on your provider's servers.

curl -X DELETE "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com" \
  -H "Authorization: Bearer $TOKEN"

Warning: This is irreversible inside SpiderMail — the mailbox's messages, threads, and flags are deleted. The underlying email account at your provider is unaffected, so you can always re-connect it later (a fresh connect re-polls from the provider).

Mailbox limits

The number of mailboxes you can connect is capped per plan. When you reach the cap, registering another mailbox returns 403 with a resource_quota_exceeded body that names the limit and your current usage. Delete an unused mailbox or upgrade your plan to add more.

Next steps

1. Send, reply, and forward from a connected mailbox.

2. Configure a default template for consistent branding.

3. Full endpoint details in the Mailbox API.