threads.md

threads

Conversation threads. The machinemail threads commands: arguments, flags, examples and the API routes they call.

Source: https://machinemail.dev/docs/cli/commands/threads

Conversation threads. Also spelled thread.

Command	Summary
`threads delete`	Delete thread
`threads get`	Get thread
`threads list`	List threads
`threads search`	Search threads
`threads update`	Update thread

Every command also takes the global flags.

threads delete

Delete thread.

Also: machinemail threads rm.

Permanently deletes the thread and its messages (up to 500).

Requires the thread_delete permission.

machinemail threads delete <thread-id> [flags]

Arguments

Field	Type		Description
`<thread-id>`	`string`	required	ID of the thread.

Flags

Field	Type		Description
`--inbox <inbox-id>`	`string`		Use this inbox's scoped route.
`--pod <pod-id>`	`string`		Use this pod's scoped route.

Examples

machinemail threads delete thd_01m4fy8h340001pp6c74x4688h
machinemail threads delete thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev

API

DELETE /v0/threads/{thread_id}
DELETE /v0/inboxes/{inbox_id}/threads/{thread_id} with --inbox
DELETE /v0/pods/{pod_id}/threads/{thread_id} with --pod

threads get

Get thread.

The thread with its messages, which carry their bodies and trust reports. Messages come in pages of --limit (default and maximum 500): the first page has the newest messages, oldest first within the page; follow next_page_token for older ones.

Requires the thread_read permission.

machinemail threads get <thread-id> [flags]

Arguments

Flags

Field	Type	Description
`--inbox <inbox-id>`	`string`	Only this inbox.
`--pod <pod-id>`	`string`	Only this pod.
`--limit <n>`	`integer`	Maximum number of messages to return. Default and maximum 500.
`--page-token <value>`	`string`	next_page_token from the previous response: the next, older page of messages.

Examples

machinemail threads get thd_01m4fy8h340001pp6c74x4688h
machinemail threads get thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev

API

GET /v0/threads/{thread_id}
GET /v0/inboxes/{inbox_id}/threads/{thread_id} with --inbox
GET /v0/pods/{pod_id}/threads/{thread_id} with --pod

threads list

List threads.

Also: machinemail threads ls.

Threads, most recently active first. Pass --q to keep only threads with a message matching the words.

Threads with a spam, blocked, trash, quarantined or unauthenticated message are hidden unless you pass the matching --include-* flag or ask for the label in --label.

Requires the thread_read permission.

machinemail threads list [flags]

Flags

Field	Type	Description
`--inbox <inbox-id>`	`string`	Only this inbox.
`--pod <pod-id>`	`string`	Only this pod.
`--limit <n>`	`integer`	Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`.
`--page-token <value>`	`string`	next_page_token from the previous page.
`--ascending`	`boolean`	Sort oldest first.
`--label <value>`	`string[]`	Only items with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them. Repeat the flag for several values.
`--before <time>`	`string`	Only items with a timestamp before this time.
`--after <time>`	`string`	Only items with a timestamp after this time.
`--include-spam`	`boolean`	Include spam (needs label_spam_read; ignored without it).
`--include-blocked`	`boolean`	Include blocked mail (needs label_blocked_read; ignored without it).
`--include-unauthenticated`	`boolean`	Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).
`--include-trash`	`boolean`	Include trash (needs label_trash_read; ignored without it).
`--include-quarantine`	`boolean`	Include threads that have a quarantined message.
`--q <value>`	`string`	Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages.
`--all`	`boolean`	Follow next_page_token and return every page.

Examples

machinemail threads list
machinemail threads list --inbox agent@machinemail.dev
machinemail threads list --all --json | jq '.threads | length'

API

GET /v0/threads
GET /v0/inboxes/{inbox_id}/threads with --inbox
GET /v0/pods/{pod_id}/threads with --pod

threads search

Search threads.

Threads with a message whose subject, sender, recipients, body or attachment file names contain every word of --q, ordered by thread activity (not ranked by relevance). Scans the newest 500 matching messages; the response has truncated: true when it hit that cap.

Requires the thread_read permission.

machinemail threads search [flags]

Flags

Field	Type		Description
`--inbox <inbox-id>`	`string`		Only this inbox.
`--pod <pod-id>`	`string`		Only this pod.
`--q <value>`	`string`	required	Full-text filter: threads with a message whose subject, sender, recipients, body or attachment file names contain the words. Scans the newest 500 matching messages.
`--limit <n>`	`integer`		Maximum number of items to return. Default 50, maximum 500; larger values are capped. Default: `50`.
`--page-token <value>`	`string`		next_page_token from the previous page.
`--before <time>`	`string`		Only items with a timestamp before this time.
`--after <time>`	`string`		Only items with a timestamp after this time.
`--ascending`	`boolean`		Sort oldest first.
`--label <value>`	`string[]`		Only threads with any of these labels. Asking for SPAM, BLOCKED, TRASH, QUARANTINE or UNAUTHENTICATED includes them. Repeat the flag for several values.
`--include-spam`	`boolean`		Include threads with spam (needs label_spam_read; ignored without it).
`--include-blocked`	`boolean`		Include threads with blocked mail (needs label_blocked_read; ignored without it).
`--include-unauthenticated`	`boolean`		Include threads with unauthenticated mail (needs label_unauthenticated_read; ignored without it).
`--include-trash`	`boolean`		Include threads with trash (needs label_trash_read; ignored without it).
`--include-quarantine`	`boolean`		Include threads that have a quarantined message.
`--all`	`boolean`		Follow next_page_token and return every page.

Examples

machinemail threads search --q invoice
machinemail threads search --q invoice --inbox agent@machinemail.dev
machinemail threads search --q invoice --all --json | jq '.threads | length'

API

GET /v0/threads/search
GET /v0/inboxes/{inbox_id}/threads/search with --inbox
GET /v0/pods/{pod_id}/threads/search with --pod

threads update

Update thread.

Adds and removes labels on every message in the thread (up to 500 messages); the thread labels are their union. Labels are free strings, system labels included. Returns the updated thread without messages.

Requires the message_update permission.

machinemail threads update <thread-id> [flags]

Arguments

Flags

Field	Type		Description
`--inbox <inbox-id>`	`string`		Use this inbox's scoped route.
`--pod <pod-id>`	`string`		Use this pod's scoped route.
`--add-label <value>`	`string[]`		Label or labels to add to every message in the thread. Repeat the flag for several values.
`--remove-label <value>`	`string[]`		Label or labels to remove from every message in the thread. Applied after --add-label. Repeat the flag for several values.
`-d, --data <json	@file	->`	`string`

Examples

machinemail threads update thd_01m4fy8h340001pp6c74x4688h
machinemail threads update thd_01m4fy8h340001pp6c74x4688h --inbox agent@machinemail.dev
machinemail threads update thd_01m4fy8h340001pp6c74x4688h --data @body.json

API

PATCH /v0/threads/{thread_id}
PATCH /v0/inboxes/{inbox_id}/threads/{thread_id} with --inbox
PATCH /v0/pods/{pod_id}/threads/{thread_id} with --pod