Threads

Update a thread

Requires scope: manage or inbox (inbox only in a signed-in dashboard session; no API key or app can hold it). Changes read, folder, status, labels and label_ids; emits thread.updated when something changed. folder: "archive" and status: "archived" move together, and moving an archived thread anywhere else reopens it. folder: "sent" is a 422: a thread is filed there while every message in it is one the agent sent. So is status: "archived" with any folder but archive. A test key cannot move a thread holding live mail to trash (403 live_mode_required).

patch/v1/threads/{id}

Request

  • Base URL: https://api.mails.ai
  • URL: https://api.mails.ai/v1/threads/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Thread id.

Request body

labelsstring[]

Label names, up to 50, each at most 64 characters. Replaces the thread's labels. Any such name works; a name that matches a label object picks up its id and colour.

label_idsstring[]

Label object ids (lbl_…). Replaces the thread's labels with those labels' names. Sent together with labels, the thread gets both.

status'open' | 'closed' | 'archived'

"archived" also files the thread in archive; "open" or "closed" on an archived thread moves it back to the inbox.

readboolean

Mark the thread read (true) or unread (false).

folder'inbox' | 'archive' | 'spam' | 'trash'

Move the thread to inbox, archive, spam or trash. archive also sets status "archived", and moving an archived thread anywhere else reopens it. sent cannot be chosen (422): a thread is filed there while every message in it is one you sent. A thread in trash is deleted for good 30 days after it was moved there.

Response

The updated thread (no messages array).

idstring required

Thread id (thrd_…).

agent_idstring required

Id (agt_…) of the agent the thread belongs to; a thread holds one agent's mail only.

subjectstring

The subject of the thread's first message, without one leading Re:, Fwd: or Fw:. Empty when that message had no subject.

root_message_idstring

Id of the message that started the thread: msg_… for one the agent sent, rcv_… for one it received.

last_message_idstring

Id of the message that joined the thread most recently (msg_… or rcv_…).

last_message_atstring date-time

When the latest message joined the thread. The thread list is ordered by it, newest first.

message_countinteger required

How many messages have joined the thread, sent and received.

participantsstring[]

Every address the thread has involved, in lower case and without repeats: the agent's own, the senders of received mail and the recipients of sent mail.

labelsstring[]

Label names, up to 50, each at most 64 characters. Any such name works; names that match a label object also appear in label_ids.

label_idsstring[] required

Ids (lbl_…) of the label objects whose names are on this thread.

status'open' | 'closed' | 'archived' required

open (every new thread), closed or archived, changed with PATCH. archived goes with folder archive, and only an open thread takes in new mail matched by its subject (mail from someone already in the thread).

readboolean required

False once new mail arrives; set it with PATCH.

folder'inbox' | 'archive' | 'spam' | 'trash' | 'sent' required

inbox, archive, spam, trash or sent. archive goes with status archived. sent holds a thread whose messages are all ones the agent sent, until a reply moves it to the inbox. Threads in trash are deleted for good 30 days after they were trashed.

trashed_atstring date-time

When the thread was moved to trash. Present only while it is there.

test_modeboolean required

True when the thread holds no live mail: every message in it was sent with a test key (mk_test_…) or delivered through POST /v1/test/inbound. A thread with any live message is live. Its thread.* events carry the same test_mode, and GET /v1/threads lists a key's own mode unless mode says otherwise.

created_atstring date-time required

When the thread was created, with its first message.

updated_atstring date-time

When the thread last changed: a message joined it, or its read state, folder, status or labels changed.

Changes

No recorded changes to this operation across all 1 revision of this API.