threads · MachineMail Docs

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.

shell

machinemail threads delete <thread-id> [flags]

Arguments

<thread-id>stringRequired

ID of the thread.

Flags

--inbox <inbox-id>string

Use this inbox's scoped route.

--pod <pod-id>string

Use this pod's scoped route.

Examples

shell

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

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.

shell

machinemail threads get <thread-id> [flags]

Arguments

<thread-id>stringRequired

ID of the thread.

Flags

--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

shell

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.

shell

machinemail threads list [flags]

Flags

--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.

Default50

--page-token <value>string

next_page_token from the previous page.

--ascendingboolean

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-spamboolean

Include spam (needs label_spam_read; ignored without it).

--include-blockedboolean

Include blocked mail (needs label_blocked_read; ignored without it).

--include-unauthenticatedboolean

Include unauthenticated mail (needs label_unauthenticated_read; ignored without it).

--include-trashboolean

Include trash (needs label_trash_read; ignored without it).

--include-quarantineboolean

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.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

machinemail threads search [flags]

Flags

--inbox <inbox-id>string

Only this inbox.

--pod <pod-id>string

Only this pod.

--q <value>stringRequired

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.

Default50

--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.

--ascendingboolean

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-spamboolean

Include threads with spam (needs label_spam_read; ignored without it).

--include-blockedboolean

Include threads with blocked mail (needs label_blocked_read; ignored without it).

--include-unauthenticatedboolean

Include threads with unauthenticated mail (needs label_unauthenticated_read; ignored without it).

--include-trashboolean

Include threads with trash (needs label_trash_read; ignored without it).

--include-quarantineboolean

Include threads that have a quarantined message.

--allboolean

Follow next_page_token and return every page.

Examples

shell

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.

shell

machinemail threads update <thread-id> [flags]

Arguments

<thread-id>stringRequired

ID of the thread.

Flags

--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

Request body as JSON, @file or - for stdin; field flags override its keys.

Examples

shell

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