# mail.list

Search visible company mail with search: literal text in the subject, sender, body, attachment filenames and extracted document text. searchScope headers limits it to subject and sender. archived false (default) searches inbox mail, true archived mail, all both. Results include items and total; use limit and offset to continue, then mail.get for full details. Restricted messages require explicit security permission. Connected personal inbox receipt searches use evidence.inboxSearch.start/get instead.

`GET | POST /api/v1/accounting/mail.list`

Permissions: `mail:read` · Roles: admin, finance

Not available over MCP: Accountants' financial email grant isn't offered over MCP yet: phase 1 is read and comment only.

## Fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `mailbox` | string |  | Matches ^[a-z][a-z0-9_-]{1,39}$. |
| `purpose` | enum |  | One of: `unclassified`, `financial`, `billing_notice`, `account_access`, `general`, `spam`, `uncertain`. |
| `status` | enum |  | Only include records with this status. One of: `received`, `processing`, `ready`, `failed`, `quarantined`, `promoted`. |
| `read` | boolean |  |  |
| `archived` | boolean or "all" |  | false searches the inbox, true searches archived mail, all searches both. One of: `all`. |
| `search` | string |  | Case-insensitive literal text, including the email body and read attachments by default. at most 200 characters. |
| `searchScope` | enum |  | all searches subject, sender, body, attachment filenames and extracted document text. headers searches only subject and sender. One of: `all`, `headers`. Default `"all"`. |
| `limit` | integer |  | How many results to return at most. 1 to 100. Default `30`. |
| `offset` | integer |  | How many results to skip, for the next page of a list. 0 to 9007199254740991. Default `0`. |

## Example request

```bash
curl https://app.getoatmilk.com/api/v1/accounting/mail.list \
  -H "Authorization: Bearer $OATMILK_API_KEY"
```

Reference page: https://app.getoatmilk.com/docs/api/mail.list