> For the complete documentation index, see [llms.txt](https://docs.material.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.material.security/reference/api-v1/messages.md).

# Messages

**Overview**

The Messages API provides programmatic access to email messages ingested by Material Security. Retrieve a specific message by ID, or run an asynchronous search across messages using MQL (Material Query Language) to find messages matching criteria such as sender, subject, or date range.

Three endpoints make up the Messages API:

* [**Get Message**](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id) (`GET /api/v1/messages/{id}`): retrieves a single message by its encoded ID.
* [**Search Messages**](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search) (`POST /api/v1/messages/search`): starts an asynchronous search job.
* [**Get Message Search Results**](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id) (`GET /api/v1/messages/search/{id}`): retrieves the status and results of a search job.

**Response Structure**

Message responses return an ID and a `headers` object containing date, subject, sender, recipients, and authentication results by default. The search endpoints follow the standard paginated two-part structure similar to the Issues endpoints:

* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination.
* **`items`**: an array of message objects matching the search query.

Note that search is asynchronous. The [**Search Messages**](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search) endpoint returns a job ID and status immediately; results are only present in the [**Get Message Search Results**](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id) response once `status` is `"DONE"`.

**The `include` Parameter**

By default, message responses return the message ID and a `headers` object (date, subject, sender, recipients, authentication results). To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter on the [**Get Message**](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id) endpoint. Supported values are `content`, `attachments`, `issue`, `mailboxes`, and `links`. Pass multiple values as a comma-separated list (e.g. `include=content,attachments,links`).

**Want a walkthrough?**

Review [Hello World](https://docs.material.security/reference/api-v1/hello-world).

**Pagination and Rate Limiting**

* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.
* The `limit` parameter controls page size on all paginated endpoints.
* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set.
* When `hasMore` is false and `nextCursor` is null, you've reached the last page.

## Get Message

> Retrieves the full details of a single email message by its encoded ID, including sender, recipients, subject, date, and attachment metadata.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Messages","description":"**Overview**\n\nThe Messages API provides programmatic access to email messages ingested by Material Security. Retrieve a specific message by ID, or run an asynchronous search across messages using MQL (Material Query Language) to find messages matching criteria such as sender, subject, or date range.\n\nThree endpoints make up the Messages API:\n\n* **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** (`GET /api/v1/messages/{id}`): retrieves a single message by its encoded ID.  \n* **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** (`POST /api/v1/messages/search`): starts an asynchronous search job.  \n* **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** (`GET /api/v1/messages/search/{id}`): retrieves the status and results of a search job.\n\n**Response Structure**\n\nMessage responses return an ID and a `headers` object containing date, subject, sender, recipients, and authentication results by default. The search endpoints follow the standard paginated two-part structure similar to the Issues endpoints:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination.  \n* **`items`**: an array of message objects matching the search query.\n\nNote that search is asynchronous. The **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** endpoint returns a job ID and status immediately; results are only present in the **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** response once `status` is `\"DONE\"`.\n\n**The `include` Parameter**\n\nBy default, message responses return the message ID and a `headers` object (date, subject, sender, recipients, authentication results). To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter on the **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** endpoint. Supported values are `content`, `attachments`, `issue`, `mailboxes`, and `links`. Pass multiple values as a comma-separated list (e.g. `include=content,attachments,links`).\n\n**Want a walkthrough?** \n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.  \n* The `limit` parameter controls page size on all paginated endpoints.  \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set.  \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"APIMessage":{"title":"APIMessage","description":"An email message.","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.<base64>`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageHeaders"},"links":{"description":"The links found in the message body. Populated only when `include=links` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APILink"}}},"required":["meta","items"]},"issue":{"description":"The issue associated with this message. Populated only when `include=issue` is specified. Null if no issue is associated.","anyOf":[{"$ref":"#/components/schemas/APIIssueRef"},{"type":"null"}]},"content":{"description":"The body content of the message. Populated only when `include=content` is specified. Null if unavailable.","anyOf":[{"$ref":"#/components/schemas/APIMessageContent"},{"type":"null"}]},"attachments":{"description":"The attachments for this message. Populated only when `include=attachments` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIAttachment"}}},"required":["meta","items"]},"mailboxes":{"description":"The mailboxes in which this message appears. Populated only when `include=mailboxes` is specified.","type":"object","properties":{"meta":{"$ref":"#/components/schemas/CollectionMeta"},"items":{"type":"array","items":{"$ref":"#/components/schemas/APIMailbox"}}},"required":["meta","items"]}},"required":["id","headers"]},"APIMessageHeaders":{"title":"APIMessageHeaders","description":"Header-derived fields for the message.","type":"object","properties":{"messageId":{"description":"The RFC 2822 Message-ID header value for this message.","type":"string"},"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"subject":{"description":"The subject line of the email. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"from":{"description":"The sender address of the message. Typically the From header, but may be the original sender for messages forwarded through customer-owned infrastructure. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"to":{"description":"The recipients on the To header. Addresses only; display names are not included.","type":"array","items":{"type":"string"}},"cc":{"description":"The recipients on the Cc header. Addresses only; display names are not included.","type":"array","items":{"type":"string"}},"bcc":{"description":"The recipients on the Bcc header. Addresses only; display names are not included. May include recipients reconstructed from envelope-level data when the `Bcc:` header was stripped before delivery.","type":"array","items":{"type":"string"}},"authResults":{"description":"Resolved SPF, DKIM, and DMARC results. `null` when no domain context is available to resolve your SEG settings against.","anyOf":[{"$ref":"#/components/schemas/APIAuthResults"},{"type":"null"}]}},"required":["messageId","date","subject","from","to","cc","bcc","authResults"]},"APIAuthResults":{"title":"APIAuthResults","description":"Resolved [authentication results](https://docs.material.security/learn-more/risk-areas/email-threats/investigate/issue-details) (SPF, DKIM, and DMARC) for the message. When you have a Secure Email Gateway (SEG) configured, values are pulled from the SEG’s preserved authentication-results header rather than the inline auth headers.","type":"object","properties":{"spf":{"description":"The resolved SPF authentication result.","anyOf":[{"type":"string","enum":["pass","none","neutral","temperror","permerror","softfail","policy","fail"]},{"type":"null"}]},"dkim":{"description":"The resolved DKIM authentication result.","anyOf":[{"type":"string","enum":["pass","none","neutral","temperror","permerror","policy","fail"]},{"type":"null"}]},"dmarc":{"description":"The resolved DMARC authentication result.","anyOf":[{"type":"string","enum":["pass","none","temperror","permerror","fail"]},{"type":"null"}]}},"required":["spf","dkim","dmarc"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APILink":{"title":"APILink","type":"object","properties":{"href":{"description":"The URL of the link.","type":"string"},"text":{"description":"The visible text of the link. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"type":{"description":"What kind of content the link comes from. Null if unavailable.","anyOf":[{"type":"string","enum":["a.href","img.src","script.src"]},{"type":"null"}]}},"required":["href","text","type"]},"APIIssueRef":{"title":"APIIssueRef","type":"object","properties":{"id":{"description":"The encoded ID of the associated issue. Format: `iss.1.<base64>`.","type":"string"}},"required":["id"]},"APIMessageContent":{"title":"APIMessageContent","type":"object","properties":{"parts":{"description":"The content parts that make up the message body.","type":"array","items":{"type":"object","properties":{"mime":{"description":"The MIME type of this content part (for example, `text/html`).","type":"string"},"body":{"description":"The body text of this content part.","type":"string"}},"required":["mime","body"]}}},"required":["parts"]},"APIAttachment":{"title":"APIAttachment","type":"object","properties":{"id":{"description":"The identifier for this attachment.","type":"string"},"filename":{"description":"The original filename of the attachment. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"mime":{"description":"The MIME type of the attachment (for example, `application/pdf`).","type":"string"},"size":{"description":"The size of the attachment in bytes.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hashes":{"description":"File hashes, if available","type":"object","properties":{"sha256":{"description":"The SHA-256 hash of the attachment. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]},"md5":{"description":"The MD5 hash of the attachment. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["sha256","md5"]}},"required":["id","filename","mime","size"]},"APIMailbox":{"title":"APIMailbox","type":"object","properties":{"accountId":{"description":"The encoded ID of the account that owns this mailbox. Format: `acct.1.<base64>`.","type":"string"},"email":{"description":"The email address of the mailbox.","type":"string"},"tags":{"description":"The tags associated with this mailbox.","type":"array","items":{"type":"string"}}},"required":["accountId","email","tags"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/messages/{id}":{"get":{"operationId":"getMessage","summary":"Get Message","description":"Retrieves the full details of a single email message by its encoded ID, including sender, recipients, subject, date, and attachment metadata.","tags":["Messages"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the message to retrieve. Format: `msg.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the message to retrieve. Format: `msg.1.<base64>`."},{"in":"query","name":"include","schema":{"description":"A comma-separated list of additional fields to include in the response. Valid values: `content`, `attachments`, `issue`, `mailboxes`, `links`.","type":"string"},"description":"A comma-separated list of additional fields to include in the response. Valid values: `content`, `attachments`, `issue`, `mailboxes`, `links`."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIMessage"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Search Messages

> Starts an asynchronous search job across ingested email messages using an MQL query and a date range. Returns a job ID to use when polling for results.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Messages","description":"**Overview**\n\nThe Messages API provides programmatic access to email messages ingested by Material Security. Retrieve a specific message by ID, or run an asynchronous search across messages using MQL (Material Query Language) to find messages matching criteria such as sender, subject, or date range.\n\nThree endpoints make up the Messages API:\n\n* **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** (`GET /api/v1/messages/{id}`): retrieves a single message by its encoded ID.  \n* **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** (`POST /api/v1/messages/search`): starts an asynchronous search job.  \n* **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** (`GET /api/v1/messages/search/{id}`): retrieves the status and results of a search job.\n\n**Response Structure**\n\nMessage responses return an ID and a `headers` object containing date, subject, sender, recipients, and authentication results by default. The search endpoints follow the standard paginated two-part structure similar to the Issues endpoints:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination.  \n* **`items`**: an array of message objects matching the search query.\n\nNote that search is asynchronous. The **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** endpoint returns a job ID and status immediately; results are only present in the **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** response once `status` is `\"DONE\"`.\n\n**The `include` Parameter**\n\nBy default, message responses return the message ID and a `headers` object (date, subject, sender, recipients, authentication results). To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter on the **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** endpoint. Supported values are `content`, `attachments`, `issue`, `mailboxes`, and `links`. Pass multiple values as a comma-separated list (e.g. `include=content,attachments,links`).\n\n**Want a walkthrough?** \n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.  \n* The `limit` parameter controls page size on all paginated endpoints.  \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set.  \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"SearchMessagesBody":{"title":"SearchMessagesBody","description":"Parameters for starting a message search job.","type":"object","properties":{"mqlSearchString":{"description":"The MQL (Material Query Language) query string used to filter messages (for example, `from:attacker@example.com subject:\"urgent payment\"`).","type":"string"},"startDate":{"description":"The start of the search time window in ISO 8601 format.","type":"string","format":"date-time"},"endDate":{"description":"The end of the search time window in ISO 8601 format.","type":"string","format":"date-time"},"uDomainIds":{"description":"A list of tenant domain IDs to filter results by. If omitted, searches across all tenants the caller has access to.","type":"array","items":{"type":"string"}}},"required":["mqlSearchString","startDate","endDate"]},"SearchMessagesResponse":{"title":"SearchMessagesResponse","type":"object","properties":{"id":{"description":"The encoded ID of the search job. Format: `job.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"status":{"description":"The current status of the search job. Valid values: `CREATED` (queued), `STARTED` (running), `DONE` (results ready).","type":"string","enum":["CREATED","STARTED","DONE"]}},"required":["id","status"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/messages/search":{"post":{"operationId":"searchMessages","summary":"Search Messages","description":"Starts an asynchronous search job across ingested email messages using an MQL query and a date range. Returns a job ID to use when polling for results.","tags":["Messages"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMessagesBody"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMessagesResponse"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Get Message Search Results

> Retrieves the status and results of a message search job. Poll this endpoint until status is "DONE", at which point the response includes a paginated list of matching messages.

```json
{"openapi":"3.1.0","info":{"title":"Material Security API","version":"v1"},"tags":[{"name":"Messages","description":"**Overview**\n\nThe Messages API provides programmatic access to email messages ingested by Material Security. Retrieve a specific message by ID, or run an asynchronous search across messages using MQL (Material Query Language) to find messages matching criteria such as sender, subject, or date range.\n\nThree endpoints make up the Messages API:\n\n* **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** (`GET /api/v1/messages/{id}`): retrieves a single message by its encoded ID.  \n* **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** (`POST /api/v1/messages/search`): starts an asynchronous search job.  \n* **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** (`GET /api/v1/messages/search/{id}`): retrieves the status and results of a search job.\n\n**Response Structure**\n\nMessage responses return an ID and a `headers` object containing date, subject, sender, recipients, and authentication results by default. The search endpoints follow the standard paginated two-part structure similar to the Issues endpoints:\n\n* **`meta`**: metadata about the result set, including `totalCount`, `limit`, `hasMore`, and `nextCursor` for pagination.  \n* **`items`**: an array of message objects matching the search query.\n\nNote that search is asynchronous. The **[Search Messages](https://docs.material.security/reference/api-v1/messages#post-api-v1-messages-search)** endpoint returns a job ID and status immediately; results are only present in the **[Get Message Search Results](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-search-id)** response once `status` is `\"DONE\"`.\n\n**The `include` Parameter**\n\nBy default, message responses return the message ID and a `headers` object (date, subject, sender, recipients, authentication results). To keep responses lightweight, related data is excluded unless explicitly requested with the **`include`** parameter on the **[Get Message](https://docs.material.security/reference/api-v1/messages#get-api-v1-messages-id)** endpoint. Supported values are `content`, `attachments`, `issue`, `mailboxes`, and `links`. Pass multiple values as a comma-separated list (e.g. `include=content,attachments,links`).\n\n**Want a walkthrough?** \n\nReview [Hello World](https://docs.material.security/reference/api-v1/hello-world).\n\n**Pagination and Rate Limiting**\n\n* Material APIs use **cursor-based pagination**: you pass the `nextCursor` value from one response as the `cursor` parameter in the next request.  \n* The `limit` parameter controls page size on all paginated endpoints.  \n* Every paginated response includes a `meta` object with `totalCount`, `limit`, `hasMore`, and `nextCursor` to help you know where you are in the result set.  \n* When `hasMore` is false and `nextCursor` is null, you've reached the last page.\n"}],"servers":[{"url":"https://{domain}","description":"Material Security instance","variables":{"domain":{"default":"your-instance.on.material.security","description":"Your Material Security instance domain"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-material-client-secret","description":"Material Security API key"}},"schemas":{"MessageSearchResponse":{"title":"MessageSearchResponse","type":"object","properties":{"id":{"description":"The encoded ID of the search job. Format: `job.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"status":{"description":"The current status of the search job. Valid values: `CREATED` (queued), `STARTED` (running), `DONE` (results ready).","type":"string","enum":["CREATED","STARTED","DONE"]},"data":{"description":"The search results. Present only when `status` is `\"DONE\"`.","type":"object","properties":{"meta":{"title":"CollectionMeta","description":"The pagination metadata for the search results, including `totalCount`, `limit`, `hasMore`, and `nextCursor`.","$ref":"#/components/schemas/CollectionMeta"},"items":{"description":"The list of messages matching the search query.","type":"array","items":{"$ref":"#/components/schemas/APIMessageItem"}}},"required":["meta","items"]}},"required":["id","status"]},"CollectionMeta":{"title":"CollectionMeta","type":"object","properties":{"totalCount":{"description":"The total number of items matching the query.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"The page size used for this response.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hasMore":{"description":"True if more items exist beyond the current page; false otherwise.","type":"boolean"},"nextCursor":{"description":"The cursor to fetch the next page of results. Pass this value to the `cursor` query parameter. Null if no more pages exist.","anyOf":[{"type":"string"},{"type":"null"}]}}},"APIMessageItem":{"title":"APIMessageItem","type":"object","properties":{"id":{"description":"The encoded message ID. Format: `msg.1.<base64>`.","type":"string"},"headers":{"$ref":"#/components/schemas/APIMessageItemHeaders"}},"required":["id"]},"APIMessageItemHeaders":{"title":"APIMessageItemHeaders","type":"object","properties":{"date":{"description":"The date the message was sent, in ISO 8601 format.","type":"string","format":"date-time"},"from":{"description":"The sender address of the message. Null if unavailable.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["date","from"]},"ValidationErrorResponse":{"title":"Validation Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"},"validationFailures":{"description":"List of individual validation failures when request parameters fail schema validation.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["error"]},"ErrorResponse":{"title":"Error Response","type":"object","properties":{"error":{"description":"A human-readable description of the error.","type":"string"}},"required":["error"]}}},"paths":{"/api/v1/messages/search/{id}":{"get":{"operationId":"getMessageSearch","summary":"Get Message Search Results","description":"Retrieves the status and results of a message search job. Poll this endpoint until status is \"DONE\", at which point the response includes a paginated list of matching messages.","tags":["Messages"],"parameters":[{"in":"path","name":"id","schema":{"description":"The encoded ID of the search job to retrieve. Format: `job.1.<base64>`.","type":"string","pattern":"^[a-z]{1,6}\\.[0-9]{1,2}\\.[A-Za-z0-9_-]+$"},"required":true,"description":"The encoded ID of the search job to retrieve. Format: `job.1.<base64>`."},{"in":"query","name":"cursor","schema":{"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results.","type":"string"},"description":"The pagination cursor returned in a previous response. Pass this value to retrieve the next page of results."},{"in":"query","name":"limit","schema":{"description":"The maximum number of items to return per page.","type":"integer"},"description":"The maximum number of items to return per page."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageSearchResponse"}}}},"400":{"description":"Bad request: invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"401":{"description":"Unauthorized: missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: the API key doesn't have permission to perform this action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found: the requested resource doesn't exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.material.security/reference/api-v1/messages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.