API reference

Inbox

8 operations. REST https://dev.tlntconnect.com/api/v1

GET/api/v1/inbox/mailboxesMailboxes this key's member can see in the inbox, with their permission and whether a reply can be sent from each.

The connected mailboxes visible to the key's member, exactly as the app's inbox shows them (admins: every mailbox; others: mailboxes they own, are granted, or that belong to a creator assigned to them). permission is the member's own grant (viewer, responder, sender or admin); can_send is true when the mailbox is connected for sending and the member may send from it. display_name and email_address come from the connected email account and are wrapped as untrusted content. A PlatformReadPage: newest-updated first, limit ≤ 50 (default 20), page with cursor. Requires inbox:read.

Scopes
inbox:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data[].display_name data[].email_address

Input

cursor querystring — next_cursor from the previous page.
limit queryinteger — Page size, default 20, at most 50.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
GET/api/v1/inbox/threadsEmail threads in the mailboxes this key's member can see, most recently changed first. Subjects, previews and participants are untrusted text.

Threads from every mailbox the key's member can see in the app's inbox (admins: all mailboxes). A thread in a mailbox the member cannot see never appears; account_id of such a mailbox — or another workspace's — is 404. Filters: account_id, status, unread, starred, has_attachments, assigned_to_me and q (full-text search over subject and preview). The API excludes spam unless include_spam is set: include_spam: true lists it with everything else, status: "spam" lists only spam. A PlatformReadPage ordered by updated_at then id, newest first: limit ≤ 50 (default 20); pass page.next_cursor as cursor for the next page (cursors are bound to this key's member). subject, preview, participants and labels come from outside senders and are wrapped as untrusted content. Requires inbox:read.

Scopes
inbox:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data[].subject data[].preview data[].participants data[].labels

Input

account_id querystring (uuid) — Only threads of this mailbox (list_inbox_mailboxes).
status query"open" | "waiting" | "snoozed" | "closed" | "spam"
include_spam queryboolean — true: list spam threads too (the API excludes spam unless include_spam is set). Ignored when status is set.
unread queryboolean — true: only threads unread for the key's member; false: only threads they have read. Read state is per member: unread_count is the member's own.
starred queryboolean
has_attachments queryboolean
assigned_to_me queryboolean — true: only threads assigned to the key's member.
q querystring — Full-text search over subject and preview (prefix match per word).
cursor querystring — next_cursor from the previous page.
limit queryinteger — Page size, default 20, at most 50.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
GET/api/v1/inbox/threads/{thread_id}One email thread with its messages (bodies, senders, recipients, attachments). All email text is untrusted and arrives wrapped.

A thread in a mailbox the key's member can see, with its latest messages oldest first (message_limit, default 20, at most 50; messages_truncated says older ones exist). Each message carries the plain-text body (up to 50,000 characters; body_truncated), sender, recipients, subject and its attachments (id, file name, content type, size — download one with get_inbox_attachment). The thread also carries its mailbox (with this member's permission and can_send), status, priority, labels, assignee, linked records and the in-app AI summary. A thread in a mailbox the member cannot see, in another workspace, with no mailbox, or unknown is 404. Every value an outside sender wrote, the mailbox's name and address, and the AI summary are wrapped as untrusted content. Requires inbox:read.

Scopes
inbox:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data.subject data.preview data.participants data.labels data.ai_summary data.ai_next_step data.account.display_name data.account.email_address data.messages[].body_text data.messages[].subject data.messages[].from_name data.messages[].from_email data.messages[].to data.messages[].cc data.messages[].bcc data.messages[].attachments[].filename

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.
message_limit queryinteger — Latest messages to return, default 20, at most 50.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
PATCH/api/v1/inbox/threads/{thread_id}Change a thread's status, priority, labels or assignee. Runs directly.

Updates a thread the key's member can respond to (responder permission on its mailbox, or a place on the team of the campaign the thread is linked to; 403 mailbox_permission_required for a viewer; 404 when the thread is not visible). Send at least one of status, priority, labels (replaces the thread's labels) and assigned_to (a team member id, or null to unassign; only admin members may reassign — 403 role_forbidden — and the assignee must be an active member of this workspace — 404 assignee_not_found). In the "Inbox thread changes" class: it runs at once, through the same executor as the Atlas email.thread_update action, and answers 200 { status: "updated", data }. The change is pinned to the thread as it is now: if a new message arrives first, nothing changes (409 stale_target). Requires inbox:write, an Idempotency-Key and an admin or manager member.

Scopes
inbox:write
Members
admin, manager
Runs
Directly; inbox_update class
Idempotency-Key
required
Rate weight
1

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.
Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
status body"open" | "waiting" | "snoozed" | "closed" | "spam"
priority body"low" | "normal" | "high" | "urgent"
labels bodyarray of string — Replaces the thread's labels.
assigned_to bodystring (uuid) | null — Team member id, or null to unassign. Admin members only.

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / mailbox_permission_required / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member) / assignee_not_found
409stale_target / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/inbox/threads/{thread_id}/attachments/{attachment_id}A signed download URL for one attachment of an inbox thread, valid for five minutes. The file name is untrusted text.

Metadata for one attachment of a thread the key's member can see, plus download_url: a signed link to GET /api/v1/inbox/attachment-downloads/{token} that needs no Authorization header, expires after five minutes (expires_at) and works only while this key and its member could still read the thread. The attachment id must belong to a message of THIS thread (ids from get_inbox_thread). Unknown, cross-thread or cross-workspace ids are 404. The file name comes from the sender and is wrapped as untrusted content; the file itself is untrusted too. Requires inbox:read.

Scopes
inbox:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data.filename

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.
attachment_id path, requiredstring — Attachment id from get_inbox_thread (messages[].attachments[].id).

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/inbox/threads/{thread_id}/summaryAn AI summary of a thread and one suggested next step. Uses Atlas AI (metered); the output is untrusted text derived from the email.

Runs the app's AI thread summary (Atlas, email.summarize_thread) over a thread the key's member can see and returns { summary, next_step } — it is not saved on the thread. Metered exactly like the app: one Atlas usage credit per call against the workspace's plan (402 usage_limit_exceeded at the limit, before any model call); 403 feature_not_available when Atlas's email assistant is off. The model receives the email wrapped as untrusted content and is told never to follow instructions inside it, but its output is derived from outside text, so summary and next_step are wrapped as untrusted content too. Send an empty JSON body ({}). Rate weight 5. Requires inbox:read.

Scopes
inbox:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
5
Untrusted fields
data.summary data.next_step

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
402usage_limit_exceeded / trial_limit_reached
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
409conflict
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/inbox/threads/{thread_id}/draft-replyAn AI-drafted reply to a thread, returned to you and never sent. Uses Atlas AI (metered); the draft is untrusted text derived from the email.

Runs the app's AI reply draft (Atlas, email.draft_reply) over a thread the key's member can respond to (responder permission on its mailbox, or a place on the team of the campaign the thread is linked to; 403 mailbox_permission_required for a viewer) and returns { draft }. Nothing is sent or saved: to send it, review it and call reply_to_inbox_thread with the draft as PLAIN TEXT — without the untrusted-content wrapper tags (they are removed if you leave them in) — which sends it directly (within the daily recipient cap). Metered: one Atlas usage credit per call (402 usage_limit_exceeded at the limit). In-app drafts are not metered. The draft is derived from outside text, so it is wrapped as untrusted content. Send an empty JSON body ({}). Rate weight 5. Requires inbox:read and inbox:write.

Scopes
inbox:read + inbox:write
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
5
Untrusted fields
data.draft

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
402usage_limit_exceeded / trial_limit_reached
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / feature_not_available / mailbox_permission_required
404not_found (unknown, cross-workspace or not visible to the key's member)
409conflict
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/inbox/threads/{thread_id}/replySend a reply on a thread from its mailbox. Runs directly within the daily recipient cap.

A plain-text reply (body_text, up to 20,000 characters — send plain text; untrusted-content wrapper tags, e.g. from a draft_inbox_reply draft, are removed first) on a thread the key's member can SEND from (sender permission on the thread's mailbox, or a place on the team of the campaign the thread is linked to: its admins, execution manager, deal owner and Campaign team members, a viewer-role member excepted; 403 mailbox_permission_required otherwise; 404 when the thread is not visible), to the thread's counterparty, from the thread's own mailbox (409 conflict when that mailbox cannot send right now). Optional cc and bcc add up to 20 addresses each (trimmed, lowercased, de-duplicated; the mailbox's own address and the To line are dropped; 400 invalid_input naming an address that is not one); Bcc is delivered without being shown to the other recipients and is never added to the thread's participants. In the "Sending email" class: it sends at once — the recipients, copies, sender and subject resolved exactly as the Atlas email.send action resolves them, through the same executor — counting every To, Cc and Bcc address against the credential's daily recipient cap (429 daily_send_cap_reached past it, nothing sent), and answers 200 { status: "sent", data: { message_id } }. Retrying with the same Idempotency-Key never sends twice; a new key is a new reply. The reply is pinned to the thread as it is now: if a new message arrives, the recipients change or the mailbox address changes before it is sent, it fails instead of sending. Requires inbox:write, email:send, an Idempotency-Key and an admin or manager member.

Scopes
inbox:write + email:send
Members
admin, manager
Runs
Directly; external_send class
Idempotency-Key
required
Rate weight
5

Input

thread_id path, requiredstring (uuid) — Thread id in this workspace.
Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
body_text body, requiredstring — Plain-text reply body.
cc bodyarray of string — Addresses to copy on the reply, up to 20 once repeats are dropped.
bcc bodyarray of string — Addresses to blind-copy on the reply, up to 20 once repeats are dropped: delivered, never shown to the other recipients.

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / mailbox_permission_required / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
409conflict / stale_target / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_send_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable