> 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. # Search Messages GET https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/search Full-text search across messages in the inbox, ranked by relevance. The query is matched against the sender, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and unauthenticated messages are always excluded. `limit` cannot exceed 100. Reference: https://agentmail.to/docs/api-reference/inboxes/messages/search ## 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 - `inbox_id` (string, required) — The ID of the inbox. ### Query parameters - `q` (string, required) — Full-text search query. Matched against the sender, recipients, and subject (substring) and the message body (tokenized full text). - `limit` (integer, optional) — Limit of number of items returned. - `page_token` (string, optional) — Page token for pagination. - `before` (datetime, optional) — Timestamp before which to filter by. - `after` (datetime, optional) — Timestamp after which to filter by. ## Response ### 200 - `count` (integer, required) — Number of items returned. - `messages` (list of SearchMessageItem, required) — Ordered by relevance, best match first. - `limit` (integer, optional) — Limit of number of items returned. - `next_page_token` (string, optional) — Page token for pagination. ## Errors ### 400 Validation Error - `name` (string, required) — Name of error. - `errors` (any, required) — Validation errors. Each entry has a path and a message identifying the invalid field. - `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. - `message` (string, optional) — Error message. - `fix` (string, optional) — The concrete next action that resolves the error. - `docs` (string, optional) — Link to the error reference entry for this code. ### 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 ### SearchMessageItem - `created_at` (datetime, required) — Time at which message was created. - `from` (string, required) — Address of sender. In format `username@domain.com` or `Display Name `. - `inbox_id` (string, required) — The ID of the inbox. - `labels` (list of string, required) — Labels of message. - `message_id` (string, required) — ID of message. - `size` (integer, required) — Size of message in bytes. - `thread_id` (string, required) — ID of thread. - `timestamp` (datetime, required) — Time at which message was sent or drafted. - `to` (list of string, required) — Addresses of recipients. In format `username@domain.com` or `Display Name `. - `updated_at` (datetime, required) — Time at which message was last updated. - `attachments` (list of Attachment, optional) — Attachments in message. - `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. - `bcc` (list of string, optional) — Addresses of BCC recipients. In format `username@domain.com` or `Display Name `. - `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. - `cc` (list of string, optional) — Addresses of CC recipients. In format `username@domain.com` or `Display Name `. - `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. - `highlights` (SearchMessageHighlights, optional) — Matched fragments per field. Present only when the query matched an indexed field. - `in_reply_to` (string, optional) — ID of message being replied to. - `preview` (string, optional) — Text preview of message. - `references` (list of string, optional) — IDs of previous messages in thread. - `subject` (string, optional) — Subject of message. - `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. ### SearchMessageHighlights Matched fragments per field on a message search result, with matched terms wrapped in `**`. A field key is present only when the query matched that field, so the present keys also tell you which fields produced the hit. - `from` (list of string, optional) — Matched fragments from the sender address. - `recipients` (list of string, optional) — Matched fragments from the recipient addresses (to, cc, or bcc). - `subject` (list of string, optional) — Matched fragments from the subject. - `text` (list of string, optional) — Matched fragments from the message body. ### 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 { "count": 1, "messages": [ { "created_at": "2024-01-15T09:30:00Z", "from": "from", "inbox_id": "inbox_id", "labels": [ "labels", "labels" ], "message_id": "message_id", "size": 1, "thread_id": "thread_id", "timestamp": "2024-01-15T09:30:00Z", "to": [ "to", "to" ], "updated_at": "2024-01-15T09:30:00Z", "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" } ], "authentication_results": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spf_domain": "spf_domain", "dkim_domain": "dkim_domain", "dmarc_domain": "dmarc_domain", "arc_sealer": "arc_sealer" }, "bcc": [ "bcc", "bcc" ], "calendar_event_id": "calendar_event_id", "cc": [ "cc", "cc" ], "headers": { "headers": "headers" }, "highlights": { "from": [ "from", "from" ], "recipients": [ "recipients", "recipients" ], "subject": [ "subject", "subject" ], "text": [ "text", "text" ] }, "in_reply_to": "in_reply_to", "preview": "preview", "references": [ "references", "references" ], "subject": "subject", "agent_armor": { "status": "pending", "deadline_at": "2024-01-15T09:30:00Z", "started_at": "2024-01-15T09:30:00Z" } }, { "created_at": "2024-01-15T09:30:00Z", "from": "from", "inbox_id": "inbox_id", "labels": [ "labels", "labels" ], "message_id": "message_id", "size": 1, "thread_id": "thread_id", "timestamp": "2024-01-15T09:30:00Z", "to": [ "to", "to" ], "updated_at": "2024-01-15T09:30:00Z", "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" } ], "authentication_results": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spf_domain": "spf_domain", "dkim_domain": "dkim_domain", "dmarc_domain": "dmarc_domain", "arc_sealer": "arc_sealer" }, "bcc": [ "bcc", "bcc" ], "calendar_event_id": "calendar_event_id", "cc": [ "cc", "cc" ], "headers": { "headers": "headers" }, "highlights": { "from": [ "from", "from" ], "recipients": [ "recipients", "recipients" ], "subject": [ "subject", "subject" ], "text": [ "text", "text" ] }, "in_reply_to": "in_reply_to", "preview": "preview", "references": [ "references", "references" ], "subject": "subject", "agent_armor": { "status": "pending", "deadline_at": "2024-01-15T09:30:00Z", "started_at": "2024-01-15T09:30:00Z" } } ], "limit": 1, "next_page_token": "next_page_token" } ``` **SDK Code** ```python import requests url = "https://api.agentmail.to/v0/inboxes/inbox_id/messages/search" querystring = {"q":"q"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.agentmail.to/v0/inboxes/inbox_id/messages/search?q=q'; 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/inboxes/inbox_id/messages/search?q=q" 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/inboxes/inbox_id/messages/search?q=q") 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/inboxes/inbox_id/messages/search?q=q") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.agentmail.to/v0/inboxes/inbox_id/messages/search?q=q', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.agentmail.to/v0/inboxes/inbox_id/messages/search?q=q"); 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/inboxes/inbox_id/messages/search?q=q")! 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() ```