email

Search inbound emails

searchEmails

Read-onlyIdempotent

Find particular inbound emails: a full-text query (q) over subject, body, sender and recipient, or filters on sender, recipient, subject, body, attachments, spam score, or the sent email they reply to, ranked by relevance or date. To page through the inbox newest first, or to wait for mail that has not arrived yet, use listEmails. Each row is id, thread_id, received_at, from, to, subject, status, direction, awaiting and snippet, with attachment_count, reply_count and automated when they apply; open one with getEmail. Result: emails (the matches), cursor for the next page (null at the end), total (null when not counted), total_capped, total_unavailable, sort, partial (the time limit cut the page short), facets_capped and facets_unavailable; and with include_facets, facets.

Input Schema

Name	Required	Description
`q`	No	Words to find in the subject, body, sender or recipient; each added word narrows the results. Understands quoted phrases, upper-case OR, and filters such as from:, subject: and has:attachment.
`to`	No	Which of your addresses it was sent to.
`body`	No	Words from the message text to match.
`from`	No	Who sent it: a full address, or a domain for everyone there.
`full`	No	Return the stored record, with envelope addresses, message id and spam score, instead of the compact view for reading.
`sort`	No	Order of results. Left out, best match first when there is text to rank (q, subject or body), else newest first. Use received_at_asc with date_from to poll for new mail.
`limit`	No	How many matches this call returns; follow cursor for more.
`cursor`	No	Where the next page starts: the cursor of the page before.
`status`	No	Processing stage: pending or accepted while in progress, completed when done, rejected if a filter or check refused it.
`date_to`	No	Only rows whose received_at is at or before this; a bare date covers that whole day (UTC).
`snippet`	No	Whether rows read with full: true carry highlighted match fragments for a text query. The body snippet on each row is returned either way.
`subject`	No	Words from the subject line to match.
`date_from`	No	Only rows whose received_at is at or after this date or time (UTC unless it has an offset).
`domain_id`	No	One of your receiving domains, by the id getInboxStatus returns.
`spam_score_lt`	No	Filter to emails with a spam score strictly below this value.
`has_attachment`	No	Filter to emails that have (true) or lack (false) attachments.
`include_facets`	No	Set true to also get counts by sender, domain, status and attachment presence across the whole result set.
`spam_score_gte`	No	Filter to emails with a spam score at or above this value.
`reply_to_sent_email_id`	No	Find the replies to one of your sends, by the id sendEmail or listSentEmails returned.

Output Schema

Name	Required	Description
`sort`	Yes	How the rows are ordered.
`total`	Yes	Matches; null when not counted.
`cursor`	Yes	Pass as cursor for the next page; null at the end.
`emails`	Yes	The matching emails, in sort order.
`facets`	No	With include_facets: counts over the matches; see facets_capped.
`partial`	Yes	True when the page stopped at its time limit before it filled; cursor continues the search.
`total_capped`	Yes	True when total stopped at its cap and is a lower bound.
`facets_capped`	Yes	True when facets count only the first matches up to the cap.
`total_unavailable`	Yes	True when the count did not fit its time budget, so total is null.
`facets_unavailable`	Yes	True when include_facets was set but the counts did not fit the time budget.

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedNov 3, 2026

addedOutput schema / properties / emails / items / properties / awaiting / enum
```
Added value: +[
+  "you",
+  "them"
+]
```

changedOutput schema / properties / emails / items / properties / direction / description

Previous value: -"inbound, when given: every row here is a received email."New value: +"Every row here is a received email."

addedOutput schema / properties / emails / items / properties / direction / enum
```
Added value: +[
+  "inbound"
+]
```
changedOutput schema / properties / emails / items / properties / highlights / type
```
Previous value: -"object"New value: +[
+  "object",
+  "null"
+]
```

changedOutput schema / properties / emails / items / required

Previous value: -[
-  "id",
-  "thread_id",
-  "received_at",
-  "from",
-  "to",
-  "subject",
-  "status",
-  "snippet"
-]New value: +[
+  "id",
+  "thread_id",
+  "received_at",
+  "from",
+  "to",
+  "subject",
+  "status",
+  "snippet",
+  "direction"
+]

changedOutput schema / properties / facets_capped / description

Previous value: -"Set, true, when facets count only the first matches up to the cap."New value: +"True when facets count only the first matches up to the cap."

changedOutput schema / properties / facets_unavailable / description

Previous value: -"Set, true, when facets were asked for but did not fit the time budget."New value: +"True when include_facets was set but the counts did not fit the time budget."

changedOutput schema / properties / sort / description

Previous value: -"How the rows are ordered, when given: relevance, received_at_desc or received_at_asc."New value: +"How the rows are ordered."

addedOutput schema / properties / sort / enum

Added value: +[
+  "relevance",
+  "received_at_desc",
+  "received_at_asc"
+]

changedOutput schema / properties / total / description

Previous value: -"Matches, when counted; absent when the count was skipped or ran out of time."New value: +"Matches; null when not counted."

changedOutput schema / properties / total_unavailable / description

Previous value: -"Set, true, when the count did not fit its time budget, so total is absent."New value: +"True when the count did not fit its time budget, so total is null."

changedOutput schema / required

Previous value: -[
-  "emails",
-  "cursor"
-]New value: +[
+  "emails",
+  "cursor",
+  "total",
+  "total_capped",
+  "total_unavailable",
+  "sort",
+  "partial",
+  "facets_capped",
+  "facets_unavailable"
+]

Changed12 schema fields changedNov 2, 2026

removedOutput schema / properties / emails / items / properties / awaiting / enum
```
Removed value: -[
-  "you",
-  "them"
-]
```

changedOutput schema / properties / emails / items / properties / direction / description

Previous value: -"Every row here is a received email."New value: +"inbound, when given: every row here is a received email."

removedOutput schema / properties / emails / items / properties / direction / enum
```
Removed value: -[
-  "inbound"
-]
```
changedOutput schema / properties / emails / items / properties / highlights / type
```
Previous value: -[
-  "object",
-  "null"
-]New value: +"object"
```

changedOutput schema / properties / emails / items / required

Previous value: -[
-  "id",
-  "thread_id",
-  "received_at",
-  "from",
-  "to",
-  "subject",
-  "status",
-  "snippet",
-  "direction"
-]New value: +[
+  "id",
+  "thread_id",
+  "received_at",
+  "from",
+  "to",
+  "subject",
+  "status",
+  "snippet"
+]

changedOutput schema / properties / facets_capped / description

Previous value: -"True when facets count only the first matches up to the cap."New value: +"Set, true, when facets count only the first matches up to the cap."

changedOutput schema / properties / facets_unavailable / description

Previous value: -"True when include_facets was set but the counts did not fit the time budget."New value: +"Set, true, when facets were asked for but did not fit the time budget."

changedOutput schema / properties / sort / description

Previous value: -"How the rows are ordered."New value: +"How the rows are ordered, when given: relevance, received_at_desc or received_at_asc."

removedOutput schema / properties / sort / enum

Removed value: -[
-  "relevance",
-  "received_at_desc",
-  "received_at_asc"
-]

changedOutput schema / properties / total / description

Previous value: -"Matches; null when not counted."New value: +"Matches, when counted; absent when the count was skipped or ran out of time."

changedOutput schema / properties / total_unavailable / description

Previous value: -"True when the count did not fit its time budget, so total is null."New value: +"Set, true, when the count did not fit its time budget, so total is absent."

changedOutput schema / required

Previous value: -[
-  "emails",
-  "cursor",
-  "total",
-  "total_capped",
-  "total_unavailable",
-  "sort",
-  "partial",
-  "facets_capped",
-  "facets_unavailable"
-]New value: +[
+  "emails",
+  "cursor"
+]

Changed12 schema fields changedNov 2, 2026

addedOutput schema / properties / emails / items / properties / awaiting / enum
```
Added value: +[
+  "you",
+  "them"
+]
```

changedOutput schema / properties / emails / items / properties / direction / description

Previous value: -"inbound, when given: every row here is a received email."New value: +"Every row here is a received email."

addedOutput schema / properties / emails / items / properties / direction / enum
```
Added value: +[
+  "inbound"
+]
```
changedOutput schema / properties / emails / items / properties / highlights / type
```
Previous value: -"object"New value: +[
+  "object",
+  "null"
+]
```

changedOutput schema / properties / emails / items / required

Previous value: -[
-  "id",
-  "thread_id",
-  "received_at",
-  "from",
-  "to",
-  "subject",
-  "status",
-  "snippet"
-]New value: +[
+  "id",
+  "thread_id",
+  "received_at",
+  "from",
+  "to",
+  "subject",
+  "status",
+  "snippet",
+  "direction"
+]

changedOutput schema / properties / facets_capped / description

Previous value: -"Set, true, when facets count only the first matches up to the cap."New value: +"True when facets count only the first matches up to the cap."

changedOutput schema / properties / facets_unavailable / description

Previous value: -"Set, true, when facets were asked for but did not fit the time budget."New value: +"True when include_facets was set but the counts did not fit the time budget."

changedOutput schema / properties / sort / description

Previous value: -"How the rows are ordered, when given: relevance, received_at_desc or received_at_asc."New value: +"How the rows are ordered."

addedOutput schema / properties / sort / enum

Added value: +[
+  "relevance",
+  "received_at_desc",
+  "received_at_asc"
+]

changedOutput schema / properties / total / description

Previous value: -"Matches, when counted; absent when the count was skipped or ran out of time."New value: +"Matches; null when not counted."

changedOutput schema / properties / total_unavailable / description

Previous value: -"Set, true, when the count did not fit its time budget, so total is absent."New value: +"True when the count did not fit its time budget, so total is null."

changedOutput schema / required

Previous value: -[
-  "emails",
-  "cursor"
-]New value: +[
+  "emails",
+  "cursor",
+  "total",
+  "total_capped",
+  "total_unavailable",
+  "sort",
+  "partial",
+  "facets_capped",
+  "facets_unavailable"
+]

Changed1 schema field changedOct 23, 2026

changedOutput schema / properties / sort / description

Previous value: -"How the rows are ordered, when given: relevance or received_at."New value: +"How the rows are ordered, when given: relevance, received_at_desc or received_at_asc."

Changed19 schema fields changedOct 22, 2026

changedInput schema / properties / cursor / description

Previous value: -"Where the next page starts: the meta.cursor of the page before."New value: +"Where the next page starts: the cursor of the page before."

changedInput schema / properties / full / description

Previous value: -"Return the stored record, with delivery, webhook and classification state, instead of the compact view for reading."New value: +"Return the stored record, with envelope addresses, message id and spam score, instead of the compact view for reading."

changedInput schema / properties / limit / description

Previous value: -"How many matches this call returns; follow meta.cursor for more."New value: +"How many matches this call returns; follow cursor for more."

addedOutput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / description

Previous value: -"Envelope; the result is in data.data."New value: +"Inbound emails matching the search, and the cursor for the next page."

addedOutput schema / properties / cursor

Added value: +{
+  "description": "Pass as cursor for the next page; null at the end.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

removedOutput schema / properties / data

Removed value: -{
-  "description": "API response: the result in data, or error.",
-  "properties": {
-    "data": {
-      "description": "Inbound emails matching the search.",
-      "items": {
-        "description": "One match; full adds stored fields.",
-        "properties": {
-          "attachment_count": {
-            "description": "Attachments; left out when none.",
-            "type": [
-              "number",
-              "string"
-            ]
-          },
-          "automated": {
-            "description": "Sent by a machine.",
-            "type": "boolean"
-          },
-          "awaiting": {
-            "description": "Whose turn: you or them.",
-            "type": "string"
-          },
-          "created_at": {
-            "description": "Stored time.",
-            "type": "string"
-          },
-          "direction": {
-            "description": "Always inbound.",
-            "type": "string"
-          },
-          "from": {
-            "description": "From header.",
-            "type": "string"
-          },
-          "from_email": {
-            "description": "Sender address.",
-            "type": "string"
-          },
-          "highlights": {
-            "description": "Matched fragments: subject, body.",
-            "type": "object"
-          },
-          "id": {
-            "description": "Email id, for getEmail.",
-            "type": "string"
-          },
-          "received_at": {
-            "description": "Arrival time.",
-            "type": "string"
-          },
-          "recipient": {
-            "description": "Envelope recipient.",
-            "type": "string"
-          },
-          "reply_count": {
-            "description": "Replies you sent to it.",
-            "type": [
-              "number",
-              "string"
-            ]
-          },
-          "score": {
-            "description": "Relevance; full only.",
-            "type": [
-              "number",
-              "string"
-            ]
-          },
-          "sender": {
-            "description": "Envelope sender.",
-            "type": "string"
-          },
-          "snippet": {
-            "description": "Start of the body.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "spam_score": {
-            "description": "Higher is spammier.",
-            "type": [
-              "number",
-              "string",
-              "null"
-            ]
-          },
-          "status": {
-            "description": "Processing stage.",
-            "type": "string"
-          },
-          "subject": {
-            "description": "Subject line.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "thread_id": {
-            "description": "Conversation it belongs to.",
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "to": {
-            "description": "Recipient.",
-            "type": "string"
-          },
-          "to_email": {
-            "description": "Recipient address.",
-            "type": "string"
-          }
-        },
-        "type": "object"
-      },
-      "type": [
-        "array",
-        "null"
-      ]
-    },
-    "error": {
-      "description": "Why the call was refused; absent on success.",
-      "properties": {
-        "code": {
-          "description": "Error code to branch on.",
-          "type": "string"
-        },
-        "message": {
-          "description": "What went wrong, in words.",
-          "type": "string"
-        }
-      },
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "facets": {
-      "description": "With include_facets: by_sender, by_domain, by_status.",
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "meta": {
-      "description": "cursor for the next page, total, sort; partial if cut short.",
-      "type": [
-        "object",
-        "null"
-      ]
-    },
-    "success": {
-      "description": "True when data holds the result.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}

addedOutput schema / properties / emails

Added value: +{
+  "description": "The matching emails, in sort order.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "attachment_count": {
+        "description": "Attachments. Compact rows leave it out when 0.",
+        "type": "integer"
+      },
+      "automated": {
+        "description": "Sent by a machine. Compact rows set it only when true.",
+        "type": "boolean"
+      },
+      "awaiting": {
+        "description": "Whose turn, when known: you (not yet answered) or them.",
+        "type": "string"
+      },
+      "created_at": {
+        "description": "full only: when it was stored.",
+        "type": "string"
+      },
+      "direction": {
+        "description": "inbound, when given: every row here is a received email.",
+        "type": "string"
+      },
+      "from": {
+        "description": "Sender, as the From header shows it.",
+        "type": "string"
+      },
+      "from_email": {
+        "description": "full only: sender address.",
+        "type": "string"
+      },
+      "highlights": {
+        "additionalProperties": false,
+        "description": "full only, with q: matched fragments.",
+        "properties": {
+          "body": {
+            "description": "Fragments of the body.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "subject": {
+            "description": "Fragments of the subject.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "subject",
+          "body"
+        ],
+        "type": "object"
+      },
+      "id": {
+        "description": "Email id, for getEmail and getConversation.",
+        "type": "string"
+      },
+      "message_id": {
+        "description": "full only: Message-ID header.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "received_at": {
+        "description": "Arrival time.",
+        "type": "string"
+      },
+      "recipient": {
+        "description": "full only: envelope recipient.",
+        "type": "string"
+      },
+      "reply_count": {
+        "description": "Replies you sent to it. Compact rows leave it out when 0.",
+        "type": "integer"
+      },
+      "score": {
+        "description": "full only: relevance score.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "sender": {
+        "description": "full only: envelope sender.",
+        "type": "string"
+      },
+      "snippet": {
+        "description": "Start of the body; null when there is none.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "spam_score": {
+        "description": "full only: spam score; higher is spammier.",
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "status": {
+        "description": "Processing stage: pending, accepted, completed or rejected.",
+        "type": "string"
+      },
+      "subject": {
+        "description": "Subject line.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "thread_id": {
+        "description": "Conversation id; null when it is in none.",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "to": {
+        "description": "Recipient address.",
+        "type": "string"
+      },
+      "to_email": {
+        "description": "full only: recipient address.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "id",
+      "thread_id",
+      "received_at",
+      "from",
+      "to",
+      "subject",
+      "status",
+      "snippet"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / facets

Added value: +{
+  "additionalProperties": false,
+  "description": "With include_facets: counts over the matches; see facets_capped.",
+  "properties": {
+    "by_domain": {
+      "description": "Matches per sender domain, most first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "count": {
+            "description": "Matches with it.",
+            "type": "integer"
+          },
+          "value": {
+            "description": "The sender domain.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "value",
+          "count"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "by_sender": {
+      "description": "Matches per sender, most first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "count": {
+            "description": "Matches with it.",
+            "type": "integer"
+          },
+          "value": {
+            "description": "The sender.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "value",
+          "count"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "by_status": {
+      "description": "Matches per processing stage, most first.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "count": {
+            "description": "Matches with it.",
+            "type": "integer"
+          },
+          "value": {
+            "description": "The processing stage.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "value",
+          "count"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "has_attachment": {
+      "additionalProperties": false,
+      "description": "Matches with and without attachments.",
+      "properties": {
+        "false": {
+          "description": "Without attachments.",
+          "type": "integer"
+        },
+        "true": {
+          "description": "With attachments.",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "true",
+        "false"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "by_sender",
+    "by_domain",
+    "by_status",
+    "has_attachment"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / facets_capped

Added value: +{
+  "description": "Set, true, when facets count only the first matches up to the cap.",
+  "type": "boolean"
+}

addedOutput schema / properties / facets_unavailable

Added value: +{
+  "description": "Set, true, when facets were asked for but did not fit the time budget.",
+  "type": "boolean"
+}

addedOutput schema / properties / partial

Added value: +{
+  "description": "True when the page stopped at its time limit before it filled; cursor continues the search.",
+  "type": "boolean"
+}

addedOutput schema / properties / sort

Added value: +{
+  "description": "How the rows are ordered, when given: relevance or received_at.",
+  "type": "string"
+}

removedOutput schema / properties / status

Removed value: -{
-  "description": "HTTP status; 2xx on success.",
-  "type": "number"
-}

removedOutput schema / properties / tool

Removed value: -{
-  "description": "Tool that answered.",
-  "type": "string"
-}

addedOutput schema / properties / total

Added value: +{
+  "description": "Matches, when counted; absent when the count was skipped or ran out of time.",
+  "type": [
+    "integer",
+    "null"
+  ]
+}

addedOutput schema / properties / total_capped

Added value: +{
+  "description": "True when total stopped at its cap and is a lower bound.",
+  "type": "boolean"
+}

addedOutput schema / properties / total_unavailable

Added value: +{
+  "description": "Set, true, when the count did not fit its time budget, so total is absent.",
+  "type": "boolean"
+}

changedOutput schema / required

Previous value: -[
-  "tool",
-  "status",
-  "data"
-]New value: +[
+  "emails",
+  "cursor"
+]

Changed10 schema fields changedOct 22, 2026

changedInput schema / properties / q / description

Previous value: -"Search words, matched across subject, body, sender and recipient; each added word narrows the results. Understands quoted phrases, an upper-case OR between alternatives, and inline filters such as from:, subject: and has:attachment."New value: +"Words to find in the subject, body, sender or recipient; each added word narrows the results. Understands quoted phrases, upper-case OR, and filters such as from:, subject: and has:attachment."

changedInput schema / properties / sort / description

Previous value: -"Order of results. Left out, best matches come first when there is text to rank (q, subject or body), otherwise newest first. Use received_at_asc with date_from to poll for new mail."New value: +"Order of results. Left out, best match first when there is text to rank (q, subject or body), else newest first. Use received_at_asc with date_from to poll for new mail."

changedOutput schema / properties / data / description

Previous value: -"API response; result in data."New value: +"API response: the result in data, or error."

changedOutput schema / properties / data / properties / error / description

Previous value: -"Refusal: code, message."New value: +"Why the call was refused; absent on success."

addedOutput schema / properties / data / properties / error / properties

Added value: +{
+  "code": {
+    "description": "Error code to branch on.",
+    "type": "string"
+  },
+  "message": {
+    "description": "What went wrong, in words.",
+    "type": "string"
+  }
+}

addedOutput schema / properties / data / properties / error / type
```
Added value: +[
+  "object",
+  "null"
+]
```

changedOutput schema / properties / data / properties / success / description

Previous value: -"Accepted."New value: +"True when data holds the result."

changedOutput schema / properties / data / type

Previous value: -[
-  "object",
-  "string",
-  "null"
-]New value: +"object"

changedOutput schema / properties / status / description

Previous value: -"HTTP status."New value: +"HTTP status; 2xx on success."

addedOutput schema / properties / tool / description
```
Added value: +"Tool that answered."
```

Changed4 schema fields changedOct 21, 2026

changedOutput schema / description

Previous value: -"Inbound emails matching the search."New value: +"Envelope; the result is in data.data."

changedOutput schema / properties / data / description

Previous value: -"API body."New value: +"API response; result in data."

addedOutput schema / properties / data / properties / data / description
```
Added value: +"Inbound emails matching the search."
```
changedOutput schema / properties / data / properties / error / description
```
Previous value: -"Why refused."New value: +"Refusal: code, message."
```

Changed4 schema fields changedOct 20, 2026

changedInput schema / properties / body / description

Previous value: -"Text that appears in the message body."New value: +"Words from the message text to match."

changedInput schema / properties / limit / description

Previous value: -"Rows per page. Ask for fewer when you only need the top matches."New value: +"How many matches this call returns; follow meta.cursor for more."

changedInput schema / properties / q / description

Previous value: -"What you are looking for, matched in the subject, body, sender and recipient. Every word has to appear, so fewer words find more. Quote a phrase, put an upper-case OR between alternatives, and add filters such as from:, subject: or has:attachment."New value: +"Search words, matched across subject, body, sender and recipient; each added word narrows the results. Understands quoted phrases, an upper-case OR between alternatives, and inline filters such as from:, subject: and has:attachment."

changedInput schema / properties / subject / description

Previous value: -"Text that appears in the subject."New value: +"Words from the subject line to match."

Changed28 schema fields changedOct 20, 2026

changedInput schema / properties / body / description

Previous value: -"Text to look for in the body."New value: +"Text that appears in the message body."

changedInput schema / properties / cursor / description

Previous value: -"Pagination cursor from a previous response's `meta.cursor` field."New value: +"Where the next page starts: the meta.cursor of the page before."

changedInput schema / properties / date_from / description

Previous value: -"Earliest received_at to include, as a date or a date-time; times without an offset are UTC."New value: +"Only rows whose received_at is at or after this date or time (UTC unless it has an offset)."

changedInput schema / properties / date_to / description

Previous value: -"Latest received_at to include, as a date or a date-time; times without an offset are UTC."New value: +"Only rows whose received_at is at or before this; a bare date covers that whole day (UTC)."

changedInput schema / properties / domain_id / description

Previous value: -"Only emails received on this domain (an id from getInboxStatus)."New value: +"One of your receiving domains, by the id getInboxStatus returns."

changedInput schema / properties / from / description

Previous value: -"Only emails from this sender address or domain."New value: +"Who sent it: a full address, or a domain for everyone there."

changedInput schema / properties / full / description

Previous value: -"Set true for the stored record, with delivery, webhook and classification state; the default is a compact view for reading."New value: +"Return the stored record, with delivery, webhook and classification state, instead of the compact view for reading."

changedInput schema / properties / limit / description

Previous value: -"How many to return per page; use meta.cursor for the next page."New value: +"Rows per page. Ask for fewer when you only need the top matches."

changedInput schema / properties / q / description

Previous value: -"Words to find in the subject, body, sender and recipient; every word has to appear, so fewer words find more. Quote a phrase, put an upper-case OR between alternatives, and use inline filters such as from:, subject: or has:attachment."New value: +"What you are looking for, matched in the subject, body, sender and recipient. Every word has to appear, so fewer words find more. Quote a phrase, put an upper-case OR between alternatives, and add filters such as from:, subject: or has:attachment."

changedInput schema / properties / reply_to_sent_email_id / description

Previous value: -"Only replies to this sent email (its id from sendEmail or listSentEmails)."New value: +"Find the replies to one of your sends, by the id sendEmail or listSentEmails returned."

changedInput schema / properties / sort / description

Previous value: -"Sort order. Defaults to relevance when there is text to rank against (q, subject or body) and to received_at_desc otherwise; relevance without any such text is treated as received_at_desc. Use received_at_asc with date_from for polling new mail."New value: +"Order of results. Left out, best matches come first when there is text to rank (q, subject or body), otherwise newest first. Use received_at_asc with date_from to poll for new mail."

changedInput schema / properties / status / description

Previous value: -"Narrow to emails at one processing stage."New value: +"Processing stage: pending or accepted while in progress, completed when done, rejected if a filter or check refused it."

changedInput schema / properties / subject / description

Previous value: -"Text to look for in the subject."New value: +"Text that appears in the subject."

changedInput schema / properties / to / description

Previous value: -"Only emails addressed to this recipient."New value: +"Which of your addresses it was sent to."

addedOutput schema / properties / data / properties / data / items / description
```
Added value: +"One match; full adds stored fields."
```
addedOutput schema / properties / data / properties / data / items / properties / attachment_count / description
```
Added value: +"Attachments; left out when none."
```
addedOutput schema / properties / data / properties / data / items / properties / created_at / description
```
Added value: +"Stored time."
```
changedOutput schema / properties / data / properties / data / items / properties / direction / description
```
Previous value: -"inbound or outbound."New value: +"Always inbound."
```
addedOutput schema / properties / data / properties / data / items / properties / from_email / description
```
Added value: +"Sender address."
```

addedOutput schema / properties / data / properties / data / items / properties / highlights

Added value: +{
+  "description": "Matched fragments: subject, body.",
+  "type": "object"
+}

addedOutput schema / properties / data / properties / data / items / properties / id / description
```
Added value: +"Email id, for getEmail."
```
addedOutput schema / properties / data / properties / data / items / properties / reply_count / description
```
Added value: +"Replies you sent to it."
```
changedOutput schema / properties / data / properties / data / items / properties / score / description
```
Previous value: -"Relevance rank."New value: +"Relevance; full only."
```
addedOutput schema / properties / data / properties / data / items / properties / subject / description
```
Added value: +"Subject line."
```
addedOutput schema / properties / data / properties / data / items / properties / thread_id / description
```
Added value: +"Conversation it belongs to."
```
addedOutput schema / properties / data / properties / data / items / properties / to_email / description
```
Added value: +"Recipient address."
```

changedOutput schema / properties / data / properties / facets / description

Previous value: -"Counts, with include_facets."New value: +"With include_facets: by_sender, by_domain, by_status."

changedOutput schema / properties / data / properties / meta / description

Previous value: -"Paging cursor."New value: +"cursor for the next page, total, sort; partial if cut short."

Changed25 schema fields changedOct 20, 2026

changedInput schema / properties / body / description

Previous value: -"Only emails whose body contains this text."New value: +"Text to look for in the body."

changedInput schema / properties / date_from / description

Previous value: -"Earliest received_at to include: a date-time (\"2026-10-01T09:00:00Z\", or with an offset) or a date (\"2026-10-01\", from 00:00 UTC). A time with no offset is read as UTC."New value: +"Earliest received_at to include, as a date or a date-time; times without an offset are UTC."

changedInput schema / properties / date_to / description

Previous value: -"Latest received_at to include: a date-time (\"2026-10-01T09:00:00Z\", or with an offset) or a date (\"2026-10-01\", through the end of that day, UTC). A time with no offset is read as UTC."New value: +"Latest received_at to include, as a date or a date-time; times without an offset are UTC."

changedInput schema / properties / full / description

Previous value: -"Set true for the record as stored. By default the result is a compact view for reading, which leaves out per-row delivery, webhook and classification state (message_id, domain and org ids, spam score, sizes, webhook status)."New value: +"Set true for the stored record, with delivery, webhook and classification state; the default is a compact view for reading."

changedInput schema / properties / limit / description

Previous value: -"Page size."New value: +"How many to return per page; use meta.cursor for the next page."

changedInput schema / properties / q / description

Previous value: -"Words to find in the subject, body, sender and recipient. All words are matched, so fewer words find more; quote a phrase. Upper-case OR between words, phrases or subject:/body: terms accepts either, and binds tighter than the implied AND (acme invoice OR receipt). OR does not join other filters; there is no NOT. Inline filters: from:, to:, subject:, body:, has:attachment, before:, after:, domain:, status:, awaiting:, automated:."New value: +"Words to find in the subject, body, sender and recipient; every word has to appear, so fewer words find more. Quote a phrase, put an upper-case OR between alternatives, and use inline filters such as from:, subject: or has:attachment."

changedInput schema / properties / status / description

Previous value: -"Only emails at this processing stage."New value: +"Narrow to emails at one processing stage."

changedInput schema / properties / subject / description

Previous value: -"Only emails whose subject contains this text."New value: +"Text to look for in the subject."

addedOutput schema / description

Added value: +"Inbound emails matching the search."

addedOutput schema / properties / data / description
```
Added value: +"API body."
```
changedOutput schema / properties / data / properties / data / items / properties / automated / description
```
Previous value: -"Sent by a machine, not a person."New value: +"Sent by a machine."
```
addedOutput schema / properties / data / properties / data / items / properties / direction / description
```
Added value: +"inbound or outbound."
```
addedOutput schema / properties / data / properties / data / items / properties / from / description
```
Added value: +"From header."
```
addedOutput schema / properties / data / properties / data / items / properties / received_at / description
```
Added value: +"Arrival time."
```
addedOutput schema / properties / data / properties / data / items / properties / recipient / description
```
Added value: +"Envelope recipient."
```
addedOutput schema / properties / data / properties / data / items / properties / sender / description
```
Added value: +"Envelope sender."
```
addedOutput schema / properties / data / properties / data / items / properties / snippet / description
```
Added value: +"Start of the body."
```
addedOutput schema / properties / data / properties / data / items / properties / spam_score / description
```
Added value: +"Higher is spammier."
```
addedOutput schema / properties / data / properties / data / items / properties / status / description
```
Added value: +"Processing stage."
```
addedOutput schema / properties / data / properties / data / items / properties / to / description
```
Added value: +"Recipient."
```
addedOutput schema / properties / data / properties / error / description
```
Added value: +"Why refused."
```
addedOutput schema / properties / data / properties / facets / description
```
Added value: +"Counts, with include_facets."
```
addedOutput schema / properties / data / properties / meta / description
```
Added value: +"Paging cursor."
```
addedOutput schema / properties / data / properties / success / description
```
Added value: +"Accepted."
```
addedOutput schema / properties / status / description
```
Added value: +"HTTP status."
```

Changed14 schema fields changedOct 20, 2026

changedInput schema / properties / body / description

Previous value: -"Filter to emails whose body contains this string."New value: +"Only emails whose body contains this text."

changedInput schema / properties / date_from / description

Previous value: -"Inclusive lower bound on received_at. An ISO 8601 date-time with Z or a UTC offset (\"2026-10-01T09:00:00Z\", \"2026-10-01T09:00:00-04:00\"), or a calendar date (\"2026-10-01\"), which starts at 00:00 UTC. A time with no offset is read as UTC."New value: +"Earliest received_at to include: a date-time (\"2026-10-01T09:00:00Z\", or with an offset) or a date (\"2026-10-01\", from 00:00 UTC). A time with no offset is read as UTC."

changedInput schema / properties / date_to / description

Previous value: -"Inclusive upper bound on received_at. An ISO 8601 date-time with Z or a UTC offset (\"2026-10-01T09:00:00Z\", \"2026-10-01T09:00:00-04:00\"), or a calendar date (\"2026-10-01\"), which runs to the end of that day, UTC. A time with no offset is read as UTC."New value: +"Latest received_at to include: a date-time (\"2026-10-01T09:00:00Z\", or with an offset) or a date (\"2026-10-01\", through the end of that day, UTC). A time with no offset is read as UTC."

changedInput schema / properties / domain_id / description

Previous value: -"Filter to emails received on a specific verified domain."New value: +"Only emails received on this domain (an id from getInboxStatus)."

changedInput schema / properties / from / description

Previous value: -"Filter to emails from this sender address or domain."New value: +"Only emails from this sender address or domain."

changedInput schema / properties / limit / description

Previous value: -"Most emails to return in one page."New value: +"Page size."

changedInput schema / properties / q / description

Previous value: -"Full-text query matched across subject, body, sender, and recipient. Every word must match, so fewer words find more; put a phrase in double quotes. An upper-case OR between words, phrases, or subject: / body: terms accepts either (invoice OR receipt). OR binds tighter than the implicit AND: acme invoice OR receipt means acme and either invoice or receipt. OR cannot join the other field filters, and there is no NOT. Field filters can be written inline: from:, to:, subject:, body:, has:attachment, before:, after:, domain:, status:, awaiting:, automated:."New value: +"Words to find in the subject, body, sender and recipient. All words are matched, so fewer words find more; quote a phrase. Upper-case OR between words, phrases or subject:/body: terms accepts either, and binds tighter than the implied AND (acme invoice OR receipt). OR does not join other filters; there is no NOT. Inline filters: from:, to:, subject:, body:, has:attachment, before:, after:, domain:, status:, awaiting:, automated:."

changedInput schema / properties / reply_to_sent_email_id / description

Previous value: -"Filter to inbound emails that are replies to a specific sent email ID."New value: +"Only replies to this sent email (its id from sendEmail or listSentEmails)."

changedInput schema / properties / status / description

Previous value: -"Filter to emails in this processing status."New value: +"Only emails at this processing stage."

changedInput schema / properties / subject / description

Previous value: -"Filter to emails whose subject contains this string."New value: +"Only emails whose subject contains this text."

changedInput schema / properties / to / description

Previous value: -"Filter to emails addressed to this recipient."New value: +"Only emails addressed to this recipient."

addedOutput schema / properties / data / properties / data / items / properties / automated / description
```
Added value: +"Sent by a machine, not a person."
```
addedOutput schema / properties / data / properties / data / items / properties / awaiting / description
```
Added value: +"Whose turn: you or them."
```
addedOutput schema / properties / data / properties / data / items / properties / score / description
```
Added value: +"Relevance rank."
```

Changed7 schema fields changedOct 18, 2026

changedInput schema / properties / include_facets / description

Previous value: -"Set true to also get aggregated facet counts (by sender, domain, status and whether there is an attachment) for the whole result set. Left out by default."New value: +"Set true to also get counts by sender, domain, status and attachment presence across the whole result set."

changedInput schema / properties / limit / description

Previous value: -"Maximum number of emails to return (1 to 100, default 50)."New value: +"Most emails to return in one page."

changedInput schema / properties / snippet / description

Previous value: -"Whether rows read with full: true carry highlighted match fragments for a text query (default true). The body snippet on each row is returned either way."New value: +"Whether rows read with full: true carry highlighted match fragments for a text query. The body snippet on each row is returned either way."

removedOutput schema / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / data / properties

Added value: +{
+  "data": {
+    "items": {
+      "properties": {
+        "attachment_count": {
+          "type": [
+            "number",
+            "string"
+          ]
+        },
+        "automated": {
+          "type": "boolean"
+        },
+        "awaiting": {
+          "type": "string"
+        },
+        "created_at": {
+          "type": "string"
+        },
+        "direction": {
+          "type": "string"
+        },
+        "from": {
+          "type": "string"
+        },
+        "from_email": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string"
+        },
+        "received_at": {
+          "type": "string"
+        },
+        "recipient": {
+          "type": "string"
+        },
+        "reply_count": {
+          "type": [
+            "number",
+            "string"
+          ]
+        },
+        "score": {
+          "type": [
+            "number",
+            "string"
+          ]
+        },
+        "sender": {
+          "type": "string"
+        },
+        "snippet": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "spam_score": {
+          "type": [
+            "number",
+            "string",
+            "null"
+          ]
+        },
+        "status": {
+          "type": "string"
+        },
+        "subject": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "thread_id": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "to": {
+          "type": "string"
+        },
+        "to_email": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "type": [
+      "array",
+      "null"
+    ]
+  },
+  "error": {},
+  "facets": {
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "meta": {
+    "type": [
+      "object",
+      "null"
+    ]
+  },
+  "success": {
+    "type": "boolean"
+  }
+}

addedOutput schema / properties / data / type

Added value: +[
+  "object",
+  "string",
+  "null"
+]

removedOutput schema / properties / statusText
```
Removed value: -{
-  "type": "string"
-}
```

Changed20 schema fields changedOct 8, 2026

changedInput schema / properties / date_from / description

Previous value: -"Inclusive lower bound on received_at (ISO 8601)."New value: +"Inclusive lower bound on received_at. An ISO 8601 date-time with Z or a UTC offset (\"2026-10-01T09:00:00Z\", \"2026-10-01T09:00:00-04:00\"), or a calendar date (\"2026-10-01\"), which starts at 00:00 UTC. A time with no offset is read as UTC."

removedInput schema / properties / date_from / format
```
Removed value: -"date-time"
```

changedInput schema / properties / date_to / description

Previous value: -"Inclusive upper bound on received_at (ISO 8601)."New value: +"Inclusive upper bound on received_at. An ISO 8601 date-time with Z or a UTC offset (\"2026-10-01T09:00:00Z\", \"2026-10-01T09:00:00-04:00\"), or a calendar date (\"2026-10-01\"), which runs to the end of that day, UTC. A time with no offset is read as UTC."

removedInput schema / properties / date_to / format
```
Removed value: -"date-time"
```

addedInput schema / properties / full

Added value: +{
+  "default": false,
+  "description": "Set true for the record as stored. By default the result is a compact view for reading, which leaves out per-row delivery, webhook and classification state (message_id, domain and org ids, spam score, sizes, webhook status).",
+  "type": "boolean"
+}

changedInput schema / properties / has_attachment / description

Previous value: -"Filter to emails that have (\"true\") or lack (\"false\") attachments."New value: +"Filter to emails that have (true) or lack (false) attachments."

removedInput schema / properties / has_attachment / enum
```
Removed value: -[
-  "true",
-  "false"
-]
```
changedInput schema / properties / has_attachment / type
```
Previous value: -"string"New value: +"boolean"
```
changedInput schema / properties / include_facets / default
```
Previous value: -"true"New value: +false
```

changedInput schema / properties / include_facets / description

Previous value: -"Include aggregated facet counts (sender, domain, status) in the response (default true)."New value: +"Set true to also get aggregated facet counts (by sender, domain, status and whether there is an attachment) for the whole result set. Left out by default."

removedInput schema / properties / include_facets / enum
```
Removed value: -[
-  "true",
-  "false"
-]
```
changedInput schema / properties / include_facets / type
```
Previous value: -"string"New value: +"boolean"
```

changedInput schema / properties / limit / description

Previous value: -"Maximum number of emails to return (1–100, default 50)."New value: +"Maximum number of emails to return (1 to 100, default 50)."

changedInput schema / properties / limit / type

Previous value: -"number"New value: +"integer"

changedInput schema / properties / q / description

Previous value: -"Full-text query matched across subject, body, sender, and recipient."New value: +"Full-text query matched across subject, body, sender, and recipient. Every word must match, so fewer words find more; put a phrase in double quotes. An upper-case OR between words, phrases, or subject: / body: terms accepts either (invoice OR receipt). OR binds tighter than the implicit AND: acme invoice OR receipt means acme and either invoice or receipt. OR cannot join the other field filters, and there is no NOT. Field filters can be written inline: from:, to:, subject:, body:, has:attachment, before:, after:, domain:, status:, awaiting:, automated:."

changedInput schema / properties / snippet / default
```
Previous value: -"true"New value: +true
```

changedInput schema / properties / snippet / description

Previous value: -"Include a short body snippet in each result (default true)."New value: +"Whether rows read with full: true carry highlighted match fragments for a text query (default true). The body snippet on each row is returned either way."

removedInput schema / properties / snippet / enum
```
Removed value: -[
-  "true",
-  "false"
-]
```

changedInput schema / properties / snippet / type

Previous value: -"string"New value: +"boolean"

changedInput schema / properties / sort / description

Previous value: -"Sort order. Use received_at_asc with date_from for polling new mail."New value: +"Sort order. Defaults to relevance when there is text to rank against (q, subject or body) and to received_at_desc otherwise; relevance without any such text is treated as received_at_desc. Use received_at_asc with date_from for polling new mail."

Changed18 schema fields changedJun 21, 2026

addedInput schema / properties / body / description

Added value: +"Filter to emails whose body contains this string."

addedInput schema / properties / cursor / description

Added value: +"Pagination cursor from a previous response's `meta.cursor` field."

addedInput schema / properties / date_from / description

Added value: +"Inclusive lower bound on received_at (ISO 8601)."

addedInput schema / properties / date_to / description

Added value: +"Inclusive upper bound on received_at (ISO 8601)."

addedInput schema / properties / domain_id / description

Added value: +"Filter to emails received on a specific verified domain."

addedInput schema / properties / from / description

Added value: +"Filter to emails from this sender address or domain."

addedInput schema / properties / has_attachment / description

Added value: +"Filter to emails that have (\"true\") or lack (\"false\") attachments."

addedInput schema / properties / include_facets / description

Added value: +"Include aggregated facet counts (sender, domain, status) in the response (default true)."

addedInput schema / properties / limit / description

Added value: +"Maximum number of emails to return (1–100, default 50)."

addedInput schema / properties / q / description

Added value: +"Full-text query matched across subject, body, sender, and recipient."

addedInput schema / properties / reply_to_sent_email_id / description

Added value: +"Filter to inbound emails that are replies to a specific sent email ID."

addedInput schema / properties / snippet / description

Added value: +"Include a short body snippet in each result (default true)."

addedInput schema / properties / sort / description

Added value: +"Sort order. Use received_at_asc with date_from for polling new mail."

addedInput schema / properties / spam_score_gte / description

Added value: +"Filter to emails with a spam score at or above this value."

addedInput schema / properties / spam_score_lt / description

Added value: +"Filter to emails with a spam score strictly below this value."

addedInput schema / properties / status / description

Added value: +"Filter to emails in this processing status."

addedInput schema / properties / subject / description

Added value: +"Filter to emails whose subject contains this string."

addedInput schema / properties / to / description

Added value: +"Filter to emails addressed to this recipient."

First observedJun 9, 2026

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint, idempotentHint and destructiveHint already declared, the description adds meaningful behavior beyond the annotations: it defines the row shape, the cursor/null-at-end paging contract, and flags like partial ('the time limit cut the page short'), total_capped, total_unavailable, facets_capped and facets_unavailable, which warn the agent that results can be truncated or uncounted. It does not discuss permissions, rate limits, or how the time limit is chosen, which is why it stops short of 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and sibling routing are front-loaded correctly, but the description then spends a long clause enumerating every returned field (id, thread_id, received_at, from, to, subject, status, direction, awaiting, snippet, attachment_count, reply_count, automated, plus emails/cursor/total/total_capped/…/facets). With an output schema present, that roster is largely redundant and buries the genuinely useful signal ('partial', cursor null at end). The two-sentence structure is dense but readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 19-parameter, zero-required search tool with annotations and an output schema, the description covers routing, paging and truncation caveats adequately. The main omission is what an unfiltered call returns (presumably everything) and any note on facet computation cost, but neither is essential to invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every one of the 19 parameters already carries its own documentation, including the sort/date_from polling advice and the q syntax. The description only summarizes the filter families ('filters on sender, recipient, subject, body, attachments, spam score, or the sent email they reply to') and adds no syntax, defaults, or interaction rules beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence names a specific verb and resource (inbound email search) and enumerates the actual search surface: full-text over subject/body/sender/recipient, plus filters on sender, recipient, subject, body, attachments, spam score and reply linkage. It explicitly contrasts with the sibling listEmails ('page through the inbox newest first', 'wait for mail that has not arrived yet') and names getEmail for opening a single row, so an agent can separate it from its siblings without reading either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing conditions: use this to find particular emails, use listEmails for chronological paging or waiting on future mail, and use getEmail to open a result. These are when-to-use and when-NOT-to-use statements naming the alternatives directly, which is the strongest form of guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All email tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?