SpiderMail

Labels, Snooze & Views

SpiderMail gives you four tools to keep an inbox under control: labels to tag messages, snooze to hide a message until later, saved views to store a filter you reuse, and bulk actions to update many messages at once. All four work the same whether a person or an agent drives them.

Labels

Labels are colored tags you define once and apply to any message. Manage the definitions with the label endpoints:

# Create a label
curl -X POST "https://spideriq.ai/api/v1/mail/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "hot-lead", "color": "#E11D48" }'

# List labels
curl "https://spideriq.ai/api/v1/mail/labels" -H "Authorization: Bearer $TOKEN"

A label has a name (1–50 characters) and a hex color (defaults to #6B7280). Update one with PATCH /mail/labels/{id} and remove it with DELETE /mail/labels/{id}.

Apply labels to a message by setting its labels array — see Reading Your Inbox:

curl -X PATCH "https://spideriq.ai/api/v1/mail/messages/5678" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["hot-lead", "follow-up"] }'

Snooze

Snoozing hides a message until a time you choose, then returns it to its original folder. Snooze with an ISO 8601 timestamp:

curl -X POST "https://spideriq.ai/api/v1/mail/messages/5678/snooze" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "snoozed_until": "2026-06-10T09:00:00Z" }'

Unsnooze early with DELETE /mail/messages/{id}/snooze, and list everything currently snoozed with GET /mail/snoozed (optionally filtered by email).

Saved views

A saved view stores a bundle of filters under a name — "Hot leads", "Unread across all mailboxes", "Bob's thread" — so you can recall it instead of re-typing the filters. Create one with a filter_config:

curl -X POST "https://spideriq.ai/api/v1/mail/views" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hot leads",
    "color": "#E11D48",
    "filter_config": { "unread_only": true, "labels": ["hot-lead"] },
    "sort_by": "date",
    "sort_direction": "DESC"
  }'

Then apply it when listing the inbox with ?view_id=:

curl "https://spideriq.ai/api/v1/mail/inbox?view_id=12&format=yaml" -H "Authorization: Bearer $TOKEN"

filter_config supports mailboxes (list of emails, omit for all), unread_only, starred_only, has_attachments, from_contains, subject_contains, labels, received_after / received_before, and direction. Views are private by default; set is_shared: true to expose a view to everyone in your workspace. Only the creator can edit or delete a view.

Bulk actions

POST /mail/messages/bulk applies one action to up to 100 messages at once:

curl -X POST "https://spideriq.ai/api/v1/mail/messages/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message_ids": [5678, 5679, 5680], "action": "mark_read" }'

The action is one of mark_read, mark_unread, archive, delete, or add_label. For add_label, also pass the label to apply.

Tip: Saved views plus bulk actions are a fast triage loop for an agent — list a view, act on the whole result set in one bulk call, repeat. No need to PATCH messages one at a time.

Next steps

  1. Search to build the filters behind a view.

  2. Read and reply to messages you have triaged.

  3. Full endpoints in the API Reference (labels, snooze, views, bulk).