Threads

A thread is a conversation in one inbox: the messages you received and the ones you sent.

How messages are grouped

SiMail decides the thread of an incoming message in this order:

1. Reply token. Outbound mail uses a Reply-To like shop-helper+<token>@simail.email. A reply to that address joins the thread the token belongs to. Tokens expire (30 days by default).
2. Headers and participants. In-Reply-To or References match a message in a thread and the sender already took part in that thread.
3. Otherwise a new thread starts. SiMail never merges threads by subject, because a subject is easy to fake.

A thread started by someone who is not a contact is marked as started by a stranger. Deleting and re-creating an inbox invalidates its old reply tokens.

Endpoints

Method and path	Permission
GET /v0/inboxes/{inbox_id}/threads	message_read
GET /v0/inboxes/{inbox_id}/threads/{thread_id}	message_read
PATCH /v0/inboxes/{inbox_id}/threads/{thread_id} (labels)	message_update
DELETE /v0/inboxes/{inbox_id}/threads/{thread_id} (to trash)	message_delete
GET /v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}	message_read
GET /v0/inboxes/{inbox_id}/threads/search?q=	message_read
GET /v0/inboxes/{inbox_id}/threads/{thread_id}/lock	message_read
GET /v0/threads, GET /v0/threads/search, GET /v0/threads/{thread_id}	message_read
GET /v0/pods/{pod_id}/threads and variants	message_read

Org-level /v0/threads covers all inboxes in your key’s scope. Query parameters are the same as for messages: labels, before, after, include_spam, include_blocked, include_trash, limit, page_token, ascending.

A thread object includes thread_id, subject, senders, recipients, message_count, size, preview, labels, last_message_id, received_timestamp, sent_timestamp, timestamp and, from GET …/threads/{thread_id}, its messages.

Labels

System labels: received, sent, unread, spam, blocked, trash, held, draft, important. You can add your own labels. A thread’s labels are the union of its messages’ labels. Agents can add and remove their own labels and unread/important; they cannot clear held, spam or blocked.

Deleting a thread or message moves it to trash; trashed items are purged after 30 days.

Human takeover

A human can lock a thread in the console to take over the conversation. While locked:

• sends in that thread return 423 thread_locked;
• already scheduled or approved messages in the thread wait and are not sent;
• GET …/threads/{thread_id}/lock shows the lock, and thread.locked / thread.unlocked events are published.

Only a human can unlock.