> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://www.agentmail.to/docs/llms.txt. # Get Thread GET https://api.agentmail.to/v0/threads/{thread_id} **CLI:** ```bash agentmail threads get --thread-id ``` Reference: https://docs.agentmail.to/api-reference/threads/get ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.agentmail.to` (prod, default) - `https://x402.api.agentmail.to` (prod-x402) - `https://mpp.api.agentmail.to` (prod-mpp) - `https://api.agentmail.eu` (eu-prod) ## Request ### Path parameters - `thread_id` (string, required) — ID of thread. ### Query parameters - `limit` (integer, optional) — Maximum number of messages to return. Cannot exceed 100. - `page_token` (string, optional) — Token returned by the previous response for retrieving the next, older page. ## Response ### 200 - `inbox_id` (string, required) — The ID of the inbox. - `thread_id` (string, required) — ID of thread. - `labels` (list of string, required) — Labels of thread. - `timestamp` (datetime, required) — Timestamp of last sent or received message. - `senders` (list of string, required) — Senders in thread. In format `username@domain.com` or `Display Name `. - `recipients` (list of string, required) — Recipients in thread. In format `username@domain.com` or `Display Name `. - `last_message_id` (string, required) — ID of last message in thread. - `message_count` (integer, required) — Number of messages in thread. - `size` (integer, required) — Size of thread in bytes. - `updated_at` (datetime, required) — Time at which thread was last updated. - `created_at` (datetime, required) — Time at which thread was created. - `count` (integer, required) — Number of messages in this response page. - `messages` (list of Message, required) — Messages in this page, ordered by `timestamp` ascending. The first page contains the newest messages; follow `next_page_token` to retrieve older pages. - `received_timestamp` (datetime, optional) — Timestamp of last received message. - `sent_timestamp` (datetime, optional) — Timestamp of last sent message. - `subject` (string, optional) — Subject of thread. - `preview` (string, optional) — Text preview of last message in thread. - `attachments` (list of Attachment, optional) — Attachments in thread. - `limit` (integer, optional) — Maximum number of messages requested for this page. - `next_page_token` (string, optional) — Token for the next, older page of messages. Omitted when this page completes the thread. ## Errors ### 404 Not Found Error - `name` (string, required) — Name of error. - `message` (string, required) — Error message. - `code` (string, optional) — Stable, machine-readable error code in snake_case (for example, not_found or missing_permission). Branch on this rather than the message text. - `fix` (string, optional) — The concrete next action that resolves the error. - `docs` (string, optional) — Link to the error reference entry for this code. ## Types ### Message - `inbox_id` (string, required) — The ID of the inbox. - `thread_id` (string, required) — ID of thread. - `message_id` (string, required) — ID of message. - `labels` (list of string, required) — Labels of message. - `timestamp` (datetime, required) — Time at which message was sent or drafted. - `from` (string, required) — Address of sender. In format `username@domain.com` or `Display Name `. - `to` (list of string, required) — Addresses of recipients. In format `username@domain.com` or `Display Name `. - `size` (integer, required) — Size of message in bytes. - `updated_at` (datetime, required) — Time at which message was last updated. - `created_at` (datetime, required) — Time at which message was created. - `reply_to` (list of string, optional) — Reply-to addresses. In format `username@domain.com` or `Display Name `. - `cc` (list of string, optional) — Addresses of CC recipients. In format `username@domain.com` or `Display Name `. - `bcc` (list of string, optional) — Addresses of BCC recipients. In format `username@domain.com` or `Display Name `. - `subject` (string, optional) — Subject of message. - `preview` (string, optional) — Text preview of message. - `text` (string, optional) — Plain text body of message. - `html` (string, optional) — HTML body of message. - `extracted_text` (string, optional) — Extracted new text content. - `extracted_html` (string, optional) — Extracted new HTML content. - `attachments` (list of Attachment, optional) — Attachments in message. - `in_reply_to` (string, optional) — ID of message being replied to. - `calendar_event_id` (string, optional) — The calendar event this email's invitation was applied to: set when the email's calendar invitation, update, cancellation or attendee reply changed the inbox's calendar, a few seconds after the email arrives. For an email about one date of a recurring event, it is that date's event ID. Absent on other emails, and on invitations that were not imported. Calendar is in AgentMail Labs. - `references` (list of string, optional) — IDs of previous messages in thread. - `headers` (map from string to string, optional) — Headers in message. `Authentication-Results` is never included, on received or sent messages: the header is unsigned, so a sender can plant a forged copy. Read `authentication_results` for the verdicts instead. Get Raw Message still returns every copy of the header. - `authentication_results` (MessageAuthenticationResults, optional) — Per-mechanism SPF, DKIM, and DMARC verdicts for a received message, each with the domain it is about, kept only where they speak for the sender's From identity. A verdict that could not be computed is absent, so the field can be `{}`. The field is absent on sent messages and on messages received before 2026-09-09; the `*_domain` and `arc_sealer` keys appear on messages received after they were introduced. The verdicts are the ones Amazon SES computed when the message reached AgentMail, with one exception. Forwarded mail fails DMARC at the receiving hop by construction. When AgentMail delivers a forwarded message as authenticated because a trusted forwarder (such as Google or Microsoft) sealed a valid ARC chain vouching for the original, the field reports the verdicts that forwarder recorded for the original message, and `arc_sealer` names it. * `spf` is about the envelope MAIL FROM (Return-Path) domain, named in `spf_domain`. It is present only when that domain is aligned with the sender's domain (the From mailbox, or the Sender header when From spans domains), meaning the two share an organizational domain: `mail.example.com` is aligned with `example.com`. An unaligned SPF result is withheld whatever its value. * `dkim` is the DKIM verdict, and `dkim_domain` the signing domain (the `d=` tag). On directly received mail the domain is named only when every DKIM signature on the message is from the same domain; a message signed by more than one domain (a sender and its email provider, for instance) keeps the verdict and omits the domain. `dkim_domain` is the signing domain as written, so compare it with the From domain before relying on it. * `dmarc` is the DMARC verdict for the From domain, named in `dmarc_domain`. * `dkim` and `dmarc` are withheld when the From list spans more than one domain or could not be fully parsed. * On forwarded mail each sealed verdict is reported only when the domain the forwarder recorded it for matches the message's current From domain. If the forwarder rewrote From, or vouched for nothing, the field is `{}`. The `unauthenticated` label, not this field, is AgentMail's acceptance decision, and it uses a looser rule, so the two can disagree: a single-From message whose only pass is an unaligned envelope SPF is delivered without the label while this field shows no pass. Use the label to tell whether AgentMail accepted the message as legitimate, and this field to see which domain each mechanism authenticated. Do not reject mail on `dmarc: fail` alone. - `agent_armor` (AgentArmorResult, optional) — Agent Armor's result for this message. Present only on messages received while Agent Armor was on for your organization. A scan starts `pending` and usually completes within seconds. `message.security.completed` is sent only for `complete` results, so a message still `pending` at `deadline_at` reads `unavailable` with no event. ### Attachment - `attachment_id` (string, required) — ID of attachment. - `size` (integer, required) — Size of attachment in bytes. - `filename` (string, optional) — Filename of attachment. - `content_type` (string, optional) — Content type of attachment. - `content_disposition` (enum, optional) — Content disposition of attachment. - Allowed values: `inline`, `attachment` - `content_id` (string, optional) — Content ID of attachment. ### MessageAuthenticationResults Per-mechanism SPF, DKIM, and DMARC verdicts for a received message, each with the domain it is about, kept only where they speak for the sender's From identity. A verdict that could not be computed is absent, so the field can be `{}`. The field is absent on sent messages and on messages received before 2026-09-09; the `*_domain` and `arc_sealer` keys appear on messages received after they were introduced. The verdicts are the ones Amazon SES computed when the message reached AgentMail, with one exception. Forwarded mail fails DMARC at the receiving hop by construction. When AgentMail delivers a forwarded message as authenticated because a trusted forwarder (such as Google or Microsoft) sealed a valid ARC chain vouching for the original, the field reports the verdicts that forwarder recorded for the original message, and `arc_sealer` names it. * `spf` is about the envelope MAIL FROM (Return-Path) domain, named in `spf_domain`. It is present only when that domain is aligned with the sender's domain (the From mailbox, or the Sender header when From spans domains), meaning the two share an organizational domain: `mail.example.com` is aligned with `example.com`. An unaligned SPF result is withheld whatever its value. * `dkim` is the DKIM verdict, and `dkim_domain` the signing domain (the `d=` tag). On directly received mail the domain is named only when every DKIM signature on the message is from the same domain; a message signed by more than one domain (a sender and its email provider, for instance) keeps the verdict and omits the domain. `dkim_domain` is the signing domain as written, so compare it with the From domain before relying on it. * `dmarc` is the DMARC verdict for the From domain, named in `dmarc_domain`. * `dkim` and `dmarc` are withheld when the From list spans more than one domain or could not be fully parsed. * On forwarded mail each sealed verdict is reported only when the domain the forwarder recorded it for matches the message's current From domain. If the forwarder rewrote From, or vouched for nothing, the field is `{}`. The `unauthenticated` label, not this field, is AgentMail's acceptance decision, and it uses a looser rule, so the two can disagree: a single-From message whose only pass is an unaligned envelope SPF is delivered without the label while this field shows no pass. Use the label to tell whether AgentMail accepted the message as legitimate, and this field to see which domain each mechanism authenticated. Do not reject mail on `dmarc: fail` alone. - `spf` (enum, optional) — Result of one email authentication mechanism, in the vocabulary of the `Authentication-Results` header (RFC 8601). `none` means there was nothing to evaluate (Amazon SES calls this GRAY): no SPF record for the envelope MAIL FROM domain, no DKIM signature to check, or no DMARC record for the From domain. - Allowed values: `pass`, `fail`, `none`, `neutral`, `softfail`, `temperror`, `permerror` - `dkim` (enum, optional) — Result of one email authentication mechanism, in the vocabulary of the `Authentication-Results` header (RFC 8601). `none` means there was nothing to evaluate (Amazon SES calls this GRAY): no SPF record for the envelope MAIL FROM domain, no DKIM signature to check, or no DMARC record for the From domain. - Allowed values: `pass`, `fail`, `none`, `neutral`, `softfail`, `temperror`, `permerror` - `dmarc` (enum, optional) — Result of one email authentication mechanism, in the vocabulary of the `Authentication-Results` header (RFC 8601). `none` means there was nothing to evaluate (Amazon SES calls this GRAY): no SPF record for the envelope MAIL FROM domain, no DKIM signature to check, or no DMARC record for the From domain. - Allowed values: `pass`, `fail`, `none`, `neutral`, `softfail`, `temperror`, `permerror` - `spf_domain` (string, optional) — Envelope MAIL FROM domain the `spf` verdict is about (`smtp.mailfrom`). - `dkim_domain` (string, optional) — Signing domain the `dkim` verdict is about (`header.d`). Present only when `dkim` is `pass` or `fail`. - `dmarc_domain` (string, optional) — From domain the `dmarc` verdict is about (`header.from`). - `arc_sealer` (string, optional) — Domain of the trusted forwarder whose ARC seal the verdicts were taken from, such as `google.com`. Present only on forwarded mail, and only beside at least one verdict. ### AgentArmorResult Agent Armor's result for this message. Present only on messages received while Agent Armor was on for your organization. A scan starts `pending` and usually completes within seconds. `message.security.completed` is sent only for `complete` results, so a message still `pending` at `deadline_at` reads `unavailable` with no event. - `status`: `pending` - `deadline_at` (datetime, required) — When the scan gives up. A result still pending then reads as `unavailable` with `deadline_exceeded`. - `started_at` (datetime, required) — When the message was received. The deadline counts from here. - `status`: `complete` - `completed_at` (datetime, required) — When the scan finished. - `model` (string, required) — Identifies the Agent Armor release that produced the verdict. Opaque; it changes when Agent Armor is updated. - `reason` (string, required) — A short explanation of the verdict. - `verdict` (enum, required) — What the scan concluded. `clear` means Agent Armor found no threat. It is advisory, not a guarantee that the message is safe. `review` means the message may try to manipulate an agent: inspect it before an agent acts on it. - Allowed values: `clear`, `review` - `manual_override` (AgentArmorManualOverride, optional) — Present on a `review` held in hold mode that someone released. - `status`: `unavailable` - `unavailable_reason` (enum, required) — Why no verdict is available. - Allowed values: `unsupported_dsn`, `payload_too_large`, `no_scannable_content`, `enqueue_failed`, `scorer_failed`, `contract_error`, `deadline_exceeded` ### AgentArmorManualOverride The record of a release of a message Agent Armor held for review. - `override_id` (string, required) — ID of the release, and the `event_id` of its `message.security.override` event. - `actor` (AgentArmorReleaseActor, required) — Who released the message. - `reason` (string, required) — Why it was released, as given by whoever released it. - `original_verdict` ("review", required) — The verdict that held the message. - `released_at` (datetime, required) — When it was released. ### AgentArmorReleaseActor Who released the message. - `kind`: `api_key` - `api_key_id` (string, required) — The API key that released it. - `kind`: `console` ## Examples **Response** ```json { "inbox_id": "inbox_id", "thread_id": "thread_id", "labels": [ "labels", "labels" ], "timestamp": "2024-01-15T09:30:00Z", "senders": [ "senders", "senders" ], "recipients": [ "recipients", "recipients" ], "last_message_id": "last_message_id", "message_count": 1, "size": 1, "updated_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-15T09:30:00Z", "count": 1, "messages": [ { "inbox_id": "inbox_id", "thread_id": "thread_id", "message_id": "message_id", "labels": [ "labels", "labels" ], "timestamp": "2024-01-15T09:30:00Z", "from": "from", "to": [ "to", "to" ], "size": 1, "updated_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-15T09:30:00Z", "reply_to": [ "reply_to", "reply_to" ], "cc": [ "cc", "cc" ], "bcc": [ "bcc", "bcc" ], "subject": "subject", "preview": "preview", "text": "text", "html": "html", "extracted_text": "extracted_text", "extracted_html": "extracted_html", "attachments": [ { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" }, { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" } ], "in_reply_to": "in_reply_to", "calendar_event_id": "calendar_event_id", "references": [ "references", "references" ], "headers": { "headers": "headers" }, "authentication_results": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spf_domain": "spf_domain", "dkim_domain": "dkim_domain", "dmarc_domain": "dmarc_domain", "arc_sealer": "arc_sealer" }, "agent_armor": { "status": "pending", "deadline_at": "2024-01-15T09:30:00Z", "started_at": "2024-01-15T09:30:00Z" } }, { "inbox_id": "inbox_id", "thread_id": "thread_id", "message_id": "message_id", "labels": [ "labels", "labels" ], "timestamp": "2024-01-15T09:30:00Z", "from": "from", "to": [ "to", "to" ], "size": 1, "updated_at": "2024-01-15T09:30:00Z", "created_at": "2024-01-15T09:30:00Z", "reply_to": [ "reply_to", "reply_to" ], "cc": [ "cc", "cc" ], "bcc": [ "bcc", "bcc" ], "subject": "subject", "preview": "preview", "text": "text", "html": "html", "extracted_text": "extracted_text", "extracted_html": "extracted_html", "attachments": [ { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" }, { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" } ], "in_reply_to": "in_reply_to", "calendar_event_id": "calendar_event_id", "references": [ "references", "references" ], "headers": { "headers": "headers" }, "authentication_results": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spf_domain": "spf_domain", "dkim_domain": "dkim_domain", "dmarc_domain": "dmarc_domain", "arc_sealer": "arc_sealer" }, "agent_armor": { "status": "pending", "deadline_at": "2024-01-15T09:30:00Z", "started_at": "2024-01-15T09:30:00Z" } } ], "received_timestamp": "2024-01-15T09:30:00Z", "sent_timestamp": "2024-01-15T09:30:00Z", "subject": "subject", "preview": "preview", "attachments": [ { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" }, { "attachment_id": "attachment_id", "size": 1, "filename": "filename", "content_type": "content_type", "content_disposition": "inline", "content_id": "content_id" } ], "limit": 1, "next_page_token": "next_page_token" } ``` **SDK Code** ```python import requests url = "https://api.agentmail.to/v0/threads/thread_id" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.agentmail.to/v0/threads/thread_id'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.agentmail.to/v0/threads/thread_id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.agentmail.to/v0/threads/thread_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.agentmail.to/v0/threads/thread_id") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.agentmail.to/v0/threads/thread_id', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.agentmail.to/v0/threads/thread_id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.agentmail.to/v0/threads/thread_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```