`evidence.inboxSearch.start`

Search the caller's own connected Gmail or Outlook inbox for the receipt, invoice, or order confirmation of purchases that still need one, with entryIds (1 to 25) and idempotencyKey. Integrations also need the mailboxes:search scope; plain read and write access never grants it. Only the caller's own inbox is ever searched, and the request is the consent for this search only: each of their inboxes is read at most once per purchase and at most one email is copied for it, and it never changes daily checks or the investigator's consent. A purchase on another member's card is not searched (it stays with that member's ask), and a contributor can only search purchases on their own cards. A merchant email or nearby processor order may be copied after financial screening. On a member-requested search only, a recent Gmail forward whose preview is truncated may instead be copied after a bounded raw read proves the single forwarded original has a confirmed order, nearby original date, merchant, exact bank-currency grand total and card suffix, and the credential screen clears it; one later judged not to be financial evidence is removed again. The purchase it was found for is suggested to matching first, which still compares it with every likely transaction: it is attached only when matching would pick that purchase anyway, and left for review otherwise. Returns the search with each purchase's state (searching, reading, attached, review, not found or skipped) and its runId. With no usable inbox the search waits for the caller to connect or resume one (status waiting_for_inbox) and says which providers are available. A member can start 60 searches an hour, run five at once and search 250 purchases a day.

POST/api/v1/accounting/evidence.inboxSearch.start

Permissions

accounting:readaccounting:writemailboxes:search

Who can call it

admin, finance, contributor

Retries

Idempotency key required

MCP

accounting_evidence_inbox_search_start

Reaches outside Oatmilk

It emails people or calls another service.

Fields

entryIdsarray of strings (ID)Required
IDs of accounting entries, from entries.list or attention.mine.
1–25 items
surfaceenum
homeentryasktransactionsapiother
idempotencyKeystringRequired
Any unique text you generate once per intended change, so a retried request only happens once. Send it as the Idempotency-Key header instead if you prefer; if you send both they must match.
8–200 characters

curl https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entryIds": [
    "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10"
  ]
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "entryIds": [
      "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10"
    ]
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "entryIds": [
            "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
        ],
    },
    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

POST/api/v1/accounting/evidence.inboxSearch.start

curl https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start \
  -H "Authorization: Bearer $OATMILK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entryIds": [
    "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10"
  ]
}'

const response = await fetch("https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OATMILK_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "entryIds": [
      "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10"
    ]
  }),
});
const { data, error } = await response.json();
if (!response.ok) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os
import uuid

import requests

response = requests.post(
    "https://app.getoatmilk.com/api/v1/accounting/evidence.inboxSearch.start",
    headers={
        "Authorization": f"Bearer {os.environ['OATMILK_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "entryIds": [
            "7f0f6c1e-1c1f-4b5e-9c8d-2f5e8e3c1a10",
        ],
    },
    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