> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.middesk.com/api-reference/entity-management/mail/list-mail-items/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server. # List mail items GET https://api.middesk.com/v1/partner/mail Reference: https://docs.middesk.com/api-reference/entity-management/mail/list-mail-items ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Query parameters - `page` (integer, optional) — Page number - `per_page` (integer, optional) — Items per page - `state` (string, optional) — Filter by state - `q` (string, optional) — Search query - `sort_by` (string, optional) — Sort field - `sort_order` (string, optional) — Sort order ## Response ### 200 mail items list - `object` (string, optional) - `data` (list of AgentMail, optional) - `url` (string, optional) - `has_more` (boolean, optional) - `count` (integer, optional) ## Types ### AgentMail - `object` (string, required) - `id` (string, required) - `created_at` (datetime, required) - `updated_at` (datetime, required) - `mail_viewed` (boolean, required) - `tag_names` (list of string, required) — List of tags associated with the mail item - `suggested_action_request` (boolean, required) - `source` (AgentMailSource, required) - `company` (AgentMailCompany, required) - `arrived_at` (datetime, optional, nullable) - `external_id` (string, optional, nullable) - `sender_name` (string, optional, nullable) - `recipient_name` (string, optional, nullable) - `agency_name` (string, optional, nullable) - `internal_status` (string, optional) — Internal processing status - `notes` (string, optional, nullable) - `document_url` (string, optional, nullable) - `summary_payload` (map from string to any, optional, nullable) - `suggested_mail_tag` (string, optional, nullable) - `suggested_partner_name` (string, optional, nullable) - `mailbox_name` (string, optional, nullable) - `registration_request_id` (string, optional, nullable) - `state` (enum, optional, nullable) — State from associated mailable - Allowed values: `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY` - `document` (map from string to any, optional, nullable) — Associated document details ### AgentMailSource - `type` (string, optional) — Type of the source object - `id` (string, optional, nullable) — ID of the source object ### AgentMailCompany - `id` (string, optional) - `legal_name` (string, optional, nullable) - `dba_name` (string, optional, nullable) - `provider_company_id` (string, optional, nullable) - `external_id` (string, optional, nullable) - `parent_account_name` (string, optional, nullable) ## Examples **Response** ```json { "object": "list", "data": [ { "object": "mail", "id": "b4c5d6e7-f8a9-0123-789a-bcdef0123456", "created_at": "2025-01-07T12:00:00Z", "updated_at": "2025-01-07T12:00:00Z", "mail_viewed": true, "tag_names": [ "tag_names" ], "suggested_action_request": true, "source": {}, "company": {}, "arrived_at": "2024-01-15T09:30:00Z", "external_id": "external_id", "sender_name": "sender_name", "recipient_name": "recipient_name", "agency_name": "agency_name", "internal_status": "internal_status", "notes": "notes", "document_url": "document_url", "summary_payload": { "key": "value" }, "suggested_mail_tag": "suggested_mail_tag", "suggested_partner_name": "suggested_partner_name", "mailbox_name": "mailbox_name", "registration_request_id": "registration_request_id", "state": "AL", "document": { "key": "value" } } ], "url": "/v1/partner/mail", "has_more": false, "count": 1 } ``` **SDK Code** ```python Mail items list import requests url = "https://api.middesk.com/v1/partner/mail" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Mail items list const url = 'https://api.middesk.com/v1/partner/mail'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Mail items list package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.middesk.com/v1/partner/mail" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Mail items list require 'uri' require 'net/http' url = URI("https://api.middesk.com/v1/partner/mail") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Mail items list import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.middesk.com/v1/partner/mail") .header("Authorization", "Bearer ") .asString(); ``` ```php Mail items list request('GET', 'https://api.middesk.com/v1/partner/mail', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Mail items list using RestSharp; var client = new RestClient("https://api.middesk.com/v1/partner/mail"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Mail items list import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.middesk.com/v1/partner/mail")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```