Inbox and uploads
Receipts, file uploads, company mail, connected inboxes and processing jobs.
56 actions
Give an AI assistant only these actions with the inbox MCP toolset.
https://app.getoatmilk.com/api/mcp?toolset=inboxdocumentRequests
- GET
documentRequests.listRead this organization's document requests and their receipt status. - GET
documentRequests.recipientsSearch active contractors and team members by name or email for a document request. - POST
documentRequests.revokeRevoke an outstanding document request and cancel queued delivery. - POST
documentRequests.sendEmail a document request with an expiring private upload link and an authenticated reply path. Requires a recipient and idempotency key.
emails
evidence
evidence.inboxSearch
- POST
evidence.inboxSearch.cancelStop an inbox search with id and idempotencyKey. Purchases not yet searched are cancelled, and no further inbox is read; one being read finishes and copies nothing more. Only the member who started it or an administrator can stop it. - GET
evidence.inboxSearch.getRead an inbox search (id), or the latest search of each purchase (entryIds, comma-separated, up to 100): its status, runId, and each purchase's state and outcome with counts of emails found and screened. Contributors see only their own searches. Mail content is never returned, except the sender, subject and date of a receipt that was copied into company mail, for people who may read company mail. - POST
evidence.inboxSearch.startSearch 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.
inbox
- GET
inbox.addressRead the address you forward receipts and invoices to. It's the organization's accounting address; anything sent to it from your verified email is filed as yours. Needs only accounting:read. Finance reads every receiving address with mail.inboundAddresses. - GET
inbox.listList receipt submissions and their review or processing state.
intake
- POST
intake.classifySuggest what an uploaded file is and where it belongs from file-type and name rules, CSV columns, readable text and the accounting classifier. Returns kind, probability, accepted, reasons and a destination such as the bank account a statement belongs to. Nothing is filed until intake.process. - POST
intake.completeVerify an uploaded intake file's size, SHA-256 hash and type by id with an idempotency key. Returns the item, ready to classify or file. - POST
intake.dismissDismiss an uploaded file that should not be filed. With removeOriginal: true, the stored original is deleted too, for an accidental upload. Adding the same file again brings it back (and uploads it again when its original was removed). Filed files can't be dismissed. - POST
intake.fromMailFile an attachment of an email in the workspace's mail (messageId, evidenceId, idempotencyKey) through universal intake: it becomes an uploaded file like a dropped one, ready for intake.classify and intake.process, and remembers the email it came from. Attachments of mail held for an administrator (quarantined, or holding sign-in or security details) can't be filed. The same file already added returns that upload with duplicate: true. - GET
intake.getRead one uploaded file with its suggestion, decision and result. Contributors can read only their own uploads. - POST
intake.inlineAdd any file Oatmilk should file in one call, for clients that can't upload to a link: filename, mimeType, contentBase64 (the file's bytes in base64, at most 2 MB), idempotencyKey and optional presetKind. Oatmilk checks the bytes, stores them privately and completes the upload, as intake.prepare, the upload and intake.complete do; a file already added returns duplicate: true. Then call intake.classify and intake.process. Retrying with the same key and file is safe. Contributors add receipts only. Larger files use intake.prepare. - GET
intake.listList uploaded files and where each one went. Filter with status (open, done, dismissed, all or one status), mine, search and since. Contributors see only their own uploads. - POST
intake.preparePrepare a private upload for any file Oatmilk should file: a receipt, vendor bill, issued invoice, bank statement, contractor agreement, tax or company document. Supply filename, mimeType, sizeBytes, sha256, idempotencyKey and optional presetKind. A file already added to the organization returns duplicate: true with addedAt. Otherwise PUT the unchanged bytes to uploadUrl, then call intake.complete. Contributors can file receipts only. - POST
intake.processFile an uploaded item as a confirmed kind (receipt, vendor_bill, issued_invoice, bank_statement, contractor_agreement, tax_document, company_document or other) with an optional target: accountId or newAccount for a CSV statement; contractorId, or newContractor (displayName, email, optional legalName, and confirmedNew once a person checked they aren't someone with the same or a close name), for an agreement, a tax document or another record kept for a contractor; taxYear for a tax document; paymentAccountId for a receipt. An agreement for a contractor that matches the one already on file (same start and end dates, rate and role) is refused with SAME_AGREEMENT until sameAgreement says what to do: link (file this upload as that agreement, adding nothing), replace (keep this copy as the agreement and void the uploaded one on file; not for one signed in Oatmilk) or keep (keep both, without reading this one's terms). Receipts and bills enter receipt processing, CSV statements are imported, agreements are kept as signed agreements, and other records go to the documents store. An issued invoice waits for review in the invoice importer; send invoiceIds once it is imported. Idempotent. Contributors can file receipts only. - GET
intake.readRead what an uploaded file says, by id, without filing or changing it: its words (text, at most 20,000 characters, with truncated true when cut short), its page count (pages), how many pages were read (readPages), whether the whole file was read (complete), and any warnings. Photos and PDFs are read with vision once and the reading is kept, so classifying the file later doesn't read it again; CSV, text, Word and email files are read directly. Spreadsheets come back without text. Payment and sign-in links are hidden, and a file holding sign-in or security details is refused. Contributors can read only their own uploads.
jobs
mail.activity
- POST
mail.approveApprove a cleared financial draft for accounting with explicit treatment and evidence provenance. - POST
mail.askAdminAsk the organization's other administrators by email to approve the new sender of a financial email, with id and idempotencyKey. Sends at most one request per member for each email and never approves the sender itself. - POST
mail.attachEvidenceAttach a cleared financial email to an existing bank purchase with current revisions and a reason. Keeps the original document kind and tax uncertainty; creates no expense and never reuses evidence for another purchase. - GET
mail.downloadPrepare an explicit short-lived download of authorized company mail evidence. - GET
mail.getRead visible company mail with immutable evidence metadata, unbooked financial drafts, the email's activity log, Oatmilk's latest review (with its one open question, if any) and how adding it to the books is going. - GET
mail.inboundAddressesList the organization's receiving email addresses. Contributors see only the accounting address. - GET
mail.listSearch 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
mail.purchaseCandidatesFind existing bank purchases to attach an authorized financial email as supporting evidence. Candidates remain separate; selecting a match requires human review. - POST
mail.rerunProcess an email again from its saved original, with id, expectedRevision, idempotencyKey and from: everything (screen, classify, read the documents with vision, fraud check and second opinion; the default, also called reclassify), reading (keep the classifier's answer and read the documents again) or review (keep the reading and ask Oatmilk's second opinion again). Every later step runs again with the workspace's current memory, people, vendors and bank lines. An email already added to the books can't be processed again: use matching.rerunEntry for its entry. A person's corrected draft is kept. Returns jobId and generation; follow the steps with runs.get (subjectType mail, subjectId the email id), then read the result with mail.get. - POST
mail.rerunManyProcess up to 50 emails again in one request, with items [{id, expectedRevision}], from (everything, reading or review, as in mail.rerun) and idempotencyKey. Each email gets its own job; returns queued [{id, jobId, generation}] and failed [{id, code, message}] so one stale or already-added email doesn't stop the rest. - POST
mail.retryQueue company mail rescreening while preserving original evidence and human draft corrections. mail.rerun does the same and can start from a later step. - POST
mail.updateMark company mail read, archived or spam with revision and idempotency checks.
mail.drafts
mail.fraud
- POST
mail.fraud.decideDecide about an email's fraud warning with id, expectedRevision, decision (genuine or fraud) and idempotencyKey. genuine clears the warning so a person can add the email to the books; fraud archives it, turns automation off for it and keeps it out of the books. Both are written to the email's activity with who decided. Nothing is ever approved automatically. - POST
mail.fraud.rescanCheck recent company mail for fraud again with the current rules: days (1 to 30, default 14) and limit (1 to 100, default 50), within a short time budget. Returns checked, flagged, raised, skipped and more. It adds or keeps warnings (an earlier reviewer clearing stands only for the same weak history signals), keeps every person's decision, and turns automation off for flagged mail.
mail.review
- POST
mail.review.answerAnswer the one question Oatmilk's review asked about an email, with id, reviewId, choiceId (a, b or c) and idempotencyKey. The choice's effect comes from the stored question: leave the draft, fix it, fix it and add it to the books through the same checks as mail.approve, or archive the email. Choices that change date, currency, total or tax only update the draft; a separate full draft review is required before booking. - POST
mail.review.memorySave or dismiss the memory entry Oatmilk suggested while reviewing an email, with id, reviewId, decision (save or dismiss) and idempotencyKey. Nothing is added to the organization's memory unless an administrator saves it.
mail.rules
mailboxes.connect
- GET
mailboxes.connect.linkGet the link where the signed-in member connects their own Gmail or Outlook inbox in Oatmilk, with optional provider and dailyChecks. Nothing is connected and no sign-in starts: connecting asks the inbox owner to agree in the provider's own window, so only they can do it. Give the person the url; connected inboxes then appear in mailboxes.list. - POST
mailboxes.connect.startStart connecting the signed-in member's own Gmail or Outlook inbox with read-only access. Returns the provider's consent URL; the member finishes in the browser. dailyChecks (default on for Connected inboxes, explicitly off for onboarding and Find in my inbox) decides whether Oatmilk checks the new inbox every day, starting 90 days back; without it the inbox is read only when the member asks, from today. Reconnecting an inbox keeps it paused if it was, and only turns daily checks on, never off. Optional returnTo (a workspace page or /onboarding) brings them back there, popup reports back to the page that opened the window and closes it, and inboxSearchId starts that member's waiting inbox search as soon as the inbox connects. mode temporary (with inboxSearchId, never dailyChecks) asks for read-only access for that one search instead: no offline access, the token is held sealed for at most an hour, bound to that search and member, never checked daily or by anything else, never listed as a connected inbox, and revoked (where the provider allows) and wiped when the search finishes, is stopped or expires. These choices stay on the server behind a single-use nonce, and the exchange uses PKCE. Dashboard only.
mailboxes
- POST
mailboxes.disconnectDisconnect a connected inbox and delete its stored access at once, with id, expectedRevision and idempotencyKey. Emails already imported stay in company mail. Only the member who connected it or an administrator can disconnect it. - GET
mailboxes.listList connected Gmail and Outlook inboxes: provider, address, who connected it, whether it is paused (scan_enabled false), checked daily (daily_checks) and offered for other members' receipts (search_for_others), the last scan, how many financial emails were imported, the latest check (a run with its status and summary), whether it is still catching up on older mail, whether scheduled checks are on, and which providers this deployment supports. Contributors see only their own. Tokens are never returned. - POST
mailboxes.scanCheck your own connected inbox for receipts and invoices now instead of waiting for the daily check; nobody can check another member's inbox, a paused one must be resumed first, and integrations need the mailboxes:search scope. Only financial emails are imported. Returns right away with the check's runId (status started, or busy with the running check's runId when one is already reading the inbox); follow it with runs.get for its steps and counts. - POST
mailboxes.updateChange a connected inbox with id, expectedRevision and idempotencyKey: scanEnabled pauses (false) or resumes (true) all reading, dailyChecks turns daily checks on (reading back 90 days) or off, searchForOthers lets Autopilot search it for other members' receipts, and scanFrom changes how far back it reads. Only the member who connected it can resume it or widen what is read, and only from the dashboard; an administrator can pause it or turn those off, and integrations can only narrow.
submissions
- GET
submissions.getGet a submission by submissionId, including its evidence, jobs, and resulting entry references even when extraction failed. - POST
submissions.releaseRelease quarantined accounting intake after administrator review. Restricted mail also requires security consent. - POST
submissions.retryRetry preserved receipt processing using submissionId, revision and idempotencyKey. - GET
submissions.tripSuggestionsSuggest visible trips for one receipt using submissionId and sourceFactIndex. Compares the receipt date and printed location even when currency is unknown; returns confidence and a reason without linking anything.
uploads
- POST
uploads.confirmConfirm uploaded evidence using submissionId and idempotencyKey. Returns a durable processing job ID; completion must be checked separately. - POST
uploads.inlineAdd a receipt, invoice or original email in one call, for clients that can't upload to a link: filename, mimeType, contentBase64 (the file's bytes in base64, at most 2 MB), idempotencyKey, and optional receiptFor (the purchase it belongs to, as in uploads.prepare) and paymentAccountId. Oatmilk checks the bytes, stores them privately and starts processing; it returns submissionId and jobId. Retrying with the same key and file is safe. Larger files use uploads.prepare and uploads.confirm. - POST
uploads.preparePrepare a private receipt or original email upload. Supply filename, mimeType, sizeBytes, sha256, idempotencyKey. If alreadyUploaded is true, the immutable original was verified: skip PUT and still confirm the returned submissionId. Otherwise upload unchanged bytes to uploadUrl, then confirm. Reuse the same idempotency key and payload on retry; changed payloads conflict. Authenticated identity is retained regardless of email headers. To add the receipt for one purchase, pass receiptFor with that entry id: it must still need a receipt or invoice (contributors: a purchase on their own card), the upload goes on its account, and matching compares the receipt with that purchase only.