`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.

GETPOST/api/v1/accounting/mail.list

Permissions

mail:read

Who can call it

admin, finance

Retries

Safe to retry: it only reads

MCP

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

Fields

mailboxstring
Matches ^[a-z][a-z0-9_-]{1,39}$
purposeenum
unclassifiedfinancialbilling_noticeaccount_accessgeneralspamuncertain
statusenum
Only include records with this status.
receivedprocessingreadyfailedquarantinedpromoted
readboolean
archivedboolean or "all"
false searches the inbox, true searches archived mail, all searches both.
all
searchstring
Case-insensitive literal text, including the email body and read attachments by default.
at most 200 characters
searchScopeenum
all searches subject, sender, body, attachment filenames and extracted document text. headers searches only subject and sender.
allheaders
Default "all"
limitinteger
How many results to return at most.
1 to 100 · Default 30
offsetinteger
How many results to skip, for the next page of a list.
0 to 9007199254740991 · Default 0

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

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/mail.list", {
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
  },
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os

import requests

response = requests.get(
    "https://app.getoatmilk.com/api/v1/accounting/mail.list",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Response

{
  "data": { … }
}

Try it

Checks your input with this action’s real schema and answers like the API, with synthetic data. No key needed, and nothing changes.

Input

GET/api/v1/accounting/mail.list

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

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/mail.list", {
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
  },
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os

import requests

response = requests.get(
    "https://app.getoatmilk.com/api/v1/accounting/mail.list",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
    },
    timeout=30,
)
payload = response.json()
if not response.ok:
    raise RuntimeError(f"{payload['error']['code']}: {payload['error']['message']}")
print(payload["data"])

Fields

Example

Try it