Skip to main content

Folders and labels

Every thread sits in one folder and can carry labels. Both work as filters on lists and search.

Mail is grouped into threads, and every thread sits in one folder and can carry labels. Agents use them the way people use a mailbox: file what is done, flag what needs a person, and find it again later.

Folders

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.

Move a thread with PATCH /v1/threads/{id}: Move the thread to inbox, archive, spam, trash or sent. archive also sets status "archived", and moving an archived thread anywhere else reopens it. sent works only while every message in the thread is one you sent (422 otherwise). A thread in trash is deleted for good 30 days after it was moved there.

cURL
# File a thread in archive and mark it read
curl -X PATCH "https://api.mails.ai/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder": "archive", "read": true }'

PATCH /v1/threads/{id} answers with the thread and previous. The fields this request changed, as they stood just before it, and only those: empty when nothing changed. Sending them back in another PATCH undoes the request, which is safer than a value read earlier, since the thread may have moved since.

Read and unread

A thread’s read flag turns false when new mail arrives; set it with PATCH /v1/threads/{id}. GET /v1/agents/{id}/inbox gives an agent’s unread count and the thread and unread counts of each folder (inbox, archive, spam, trash, sent), and the counts of each label among its inbox threads.

Opening a thread in the dashboard marks it read, unless a billing member opens it: that role only reads the mail. If your agent works through unread threads, have it follow the message.received and reply.received webhooks or a label instead, because a person opening a thread clears the flag.

Trash and deleting

Moves the thread to trash (deleted: false, the thread returned). Sent again for a thread already in trash it changes nothing, so a retried request never destroys mail. With permanent=true it deletes the thread for good, from any folder: its messages' content, raw email and attachments are removed, and the team's notes on it, and thread.deleted is emitted. Trash is also emptied automatically 30 days after a thread was moved there. A test key cannot trash or delete a thread holding live mail (403 live_mode_required). An app connected by sign-in may move a thread to trash but not delete it for good: with permanent=true it gets 403 connected_app_not_allowed.

# Move a thread to trash
curl -X DELETE "https://api.mails.ai/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $MAILS_API_KEY"

Labels

A label is a name and a colour, applied to threads. A name (unique in the workspace, ignoring case) and a colour from a fixed palette of 12. Every label in the workspace (at most 200), by name.

FieldDescription
idstring Required. Label id (lbl_…).
namestring Required. Unique in the workspace, ignoring case.
colorstring Required. The label's colour, one of 12 palette names: gray unless another was chosen. One of: gray, red, orange, amber, yellow, green, teal, cyan, blue, indigo, purple, pink.
created_atstring Required. When the label was created (UTC).
updated_atstring Required. When the label was last changed with PATCH, even by a request that left it as it was. Equal to created_at on a label never patched.

Put labels on a thread with PATCH /v1/threads/{id}. Renaming a label renames it on every thread that carries it. Deletes the label and takes it off every thread that carries it.

FieldDescription
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.
add_labelsstring[] Label names to put on the thread, keeping the ones it has (ignoring case, a name it already carries changes nothing). Applied after labels and label_ids when sent with them. A thread holds up to 50 labels (422 past that).
remove_labelsstring[] Label names to take off the thread, ignoring case; a name it does not carry changes nothing. Applied after labels and label_ids when sent with them. A name may not be in both add_labels and remove_labels (422).

labels and label_ids replace every label on the thread. To change only some, send add_labels or remove_labels with label names: the thread keeps the rest. When a request sends both kinds, the replacement happens first.

# Add one label and take another off, keeping the rest
curl -X PATCH "https://api.mails.ai/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "add_labels": ["Billing"],
    "remove_labels": ["Needs a person"]
  }'
# Create a label
curl -X POST https://api.mails.ai/v1/labels \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Needs a person", "color": "red" }'
# Put it on a thread (this replaces the thread's labels)
curl -X PATCH "https://api.mails.ai/v1/threads/$THREAD_ID" \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["Needs a person"] }'

In the dashboard

The dashboard’s inbox shows the folders and a dot for each label down the left. Press a dot to see only that label’s threads. The layouts other than Simple list group the folder you are in by label. On a thread’s own page, the × on a label takes it off the thread, with Undo.

Manage labels

Settings › Labels adds labels and renames, recolours or deletes them. The + under the dots opens it too. A thread can carry a name with no label behind it, because labels takes any name. The tab lists those names too, each with how many threads carry it and no colour yet: pick a colour and the name becomes a label, on those threads at once.

Find threads by folder and label

GET /v1/threads takes these filters, and GET /v1/search takes the same folder and label ones:

ParameterDescription
folderstring Which folder's threads to return, or all for every folder. Without it: every folder except trash. One of: inbox, archive, spam, trash, sent, all.
readboolean false for unread threads only, true for read ones.
labelstring Only threads carrying this label (a name, or a label id lbl_…).
statusstring Filter by thread status (open|closed|archived).
# Unread threads labelled "Needs a person", in every folder but trash
curl -G "https://api.mails.ai/v1/threads" \
  -H "Authorization: Bearer $MAILS_API_KEY" \
  --data-urlencode "label=Needs a person" \
  --data-urlencode "read=false"

Thread events

PATCH /v1/threads/{id} emits thread.updated when something changed, and deleting a thread for good emits thread.deleted. On a webhook endpoint: "*" is every event except thread.created, thread.updated, thread.deleted, thread.assigned, thread.unassigned, thread.note_added, message.delayed, agent.created, agent.updated, agent.deleted, draft.created, draft.updated and draft.deleted, which need naming. List the events to deliver, at least one.

Routes

Next steps

Full request and response shapes are in the API reference.

Was this page helpful?