Omniscio

Set up Email Inbound (receive email into Claude sessions)

> AgentMail intake is retired (2026-10-03). Mail sent to your AgentMail address no longer reaches your agents — send it to your support address instead, if you have set one up. Nothing is switched off for you: an install with Email Inbound still on gets one notice, with a Turn off AgentMail intake button, and the setup screens below are kept for reference. Omniscio can receive email at a dedicated inbox, run each message through a safety classifier, and either start a new Claude session for it or continue an existing email thread — with the agent's replies going back out as email on the same thread.

On this page

What it is

AgentMail intake is retired (2026-10-03). Omniscio no longer polls an AgentMail inbox, so mail sent to your AgentMail address does not reach your agents — including an inbox you set up as your own agent mail; to reach your agents by email, send it to your support address instead. That sentence appears only on an install that has a support address configured: with none set there is nowhere to send it, so the notice leaves the advice out rather than pointing at an address you do not have. If Email Inbound is still switched on, Omniscio puts ONE notice in your inbox, once per install, saying the mail is not arriving, carrying a Turn off AgentMail intake button that switches Email Inbound off. Nothing is switched off for you — it waits for your click — and the pages below describe the AgentMail setup screens, which still exist for reference.

Omniscio can receive email at a dedicated inbox, run each message through a safety classifier, and either spawn a new Claude session for it or continue an existing email-thread session. Replies the agent generates go back out as email on the same thread. This is the inbound side of email — distinct from Email Summarizer (forwarded-newsletter digests) and from Gmail integration (triaging your existing Gmail inbox inside Omniscio).

The inbox lives at AgentMail, a third-party email-for-agents service. Omniscio polls it every 30 seconds via the AgentMail HTTP API, so Omniscio must be running for new email to land in a session. The polling cadence, concurrency cap (max 10 simultaneous sessions), new-thread rate limit (max 100 brand-new threads per rolling hour), per-sender ceilings (max 10 brand-new threads, and max 20 replies on a thread you are already in, per address per rolling hour) and a per-domain ceiling (max 20 brand-new threads per domain per rolling hour, so rotating the From address inside one domain cannot mint a fresh bucket for every message) are all hardcoded — no configuration needed. Your own address, and any address you approved, is exempt from the per-sender ceilings, so your own back-and-forth is never throttled. An email that arrives while a limit is full is not dropped: it waits and is picked up on a later check once the hour frees up.

Three things have to be in place before email starts flowing:

  1. An AgentMail account + inbox (created at agentmail.to, outside Omniscio).
  2. An AgentMail API key, stored by Omniscio itself on Windows (paste it into Settings → Email Inbound — no terminal step), or in the macOS Keychain, or in the AGENTMAIL_API_KEY environment variable on Linux.
  3. The inbox address pasted into Omniscio at Settings → Email Inbound, plus optional sender + token gating.

The split exists because the API key authenticates Omniscio to AgentMail (so Omniscio can poll your messages) while the inbox address tells Omniscio which mailbox to watch. Whichever way it is stored, the key is encrypted at rest on your computer — never in a synced target in the clear.

Where to find it

How to use it

1. Create an AgentMail inbox

Sign up at agentmail.to and create an inbox. The address looks like your-name@agentmail.to. AgentMail has a free tier that's enough to evaluate the feature. Copy the API key from your AgentMail dashboard — it starts with am_us_.... The next step stores it.

2. Give Omniscio the API key

This is a one-time step. What it takes depends on your computer.

Windows — paste it into Omniscio:

  1. Open Settings → Email Inbound.
  2. Paste the key into the AgentMail API Key field and click Save.

Omniscio stores it encrypted on your computer (protected by your Windows login) and never shows the value back to you — the field just reads saved. To rotate the key later, paste a new one over it.

macOS — either paste it into the same field, or store it in your login Keychain:

security add-generic-password -s AgentMail -a api-key -w "am_us_..."

Verify with security find-generic-password -s AgentMail -a api-key -w (prints the value).

Linux — set the AGENTMAIL_API_KEY environment variable in whatever environment Omniscio inherits (e.g. ~/.profile, your launcher's Exec= entry, a systemd Environment= directive). Omniscio reads it at startup. Pasting into the Settings field works here too.

On every platform the AGENTMAIL_API_KEY environment variable, when set, takes precedence over a key saved in the app.

3. Paste the inbox address into Omniscio

  1. Open Settings → Email Inbound (gear icon, or the Settings virtual project in the sidebar).
  2. Flip Email Inbound ON.
  3. Paste your AgentMail inbox address (e.g. your-name@agentmail.to) into the Inbox ID field.
  4. Click Test. Omniscio calls listMessages against AgentMail using your stored API key, which simultaneously proves the key works AND that the inbox exists. A green "Connected successfully" confirms both. A red "Could not reach AgentMail service" means the key is missing, invalid, or doesn't own that inbox — see Troubleshooting below.

Two filters run in front of the safety classifier — neither is required, but you should configure at least one for any non-trivial use:

  • Approved Senders. Add specific addresses to restrict; everyone else is silently dropped before the classifier ever runs. An empty list is not open intake on its own — it fails closed unless an Inbox Secret Token is also configured, in which case it does become open intake and every non-self message still has to carry the token. A sender named by an enabled email-intake rule is admitted either way. Adding an address that is already on the list shows a hint and leaves your draft in the box rather than silently doing nothing.
  • Inbox Secret Token. Click the generate button to create a random token. Approved senders must include [MC:<token>] somewhere in the subject line — emails without it are silently dropped. Without a token, sender-address spoofing is your only barrier; with a token, an attacker has to know both the address you allow AND the token. The token applies to this AgentMail inbox only: mail to your Omniscio agent address is checked by that address's own sender rules instead, and the Gmail bug-report channel never looks at the token. The field is always a draft: a stored token is never shown back to you, so the box is empty (with a "replace stored token" placeholder) until you type or generate one, and nothing is saved until you click Save. Generate fills the box and reveals the new value so you can verify it first — it does not save on its own.

Both the API key and the Inbox Secret Token are paste-and-save cards with their own Save button.

The setting card warns you in amber if no token is configured.

5. (Optional) Tune the safety classifier

Below the sender filters is a Prescreen Rules textarea — the safety-classifier prompt (run on OpenRouter’s google/gemini-2.5-flash-lite, a fixed model pin, auto-falling back to Claude Haiku 4.5) that decides safe: true / false on every email before any agent sees the body. The textarea is pre-filled with the default CORE rules (block prompt-injection, exfiltration, financial actions, RCE; approve bug fixes, code review, doc edits, etc.). Edit in place; saves on blur. The JSON output contract is appended at runtime and can't be edited away. Full details: email-inbound-prescreen.md.

6. (Optional) Route bug reports to a specific project

If you want testers to email bug reports straight into a project's session, use the slug-routing layer on top of email inbound:

  1. Click the pencil icon on the project row → Edit Project.
  2. Toggle "Auto-triage incoming bug reports" ON.
  3. Set a slug (e.g. amc).

Tester emails with subject [BUG: amc] ... or [FR: amc] ... now spawn a new Claude session directly in that project, with the body fenced as untrusted external data and the agent instructed to investigate read-only and wait for approval before any code change. Full details: bug-report-intake.md.

How it behaves

Attachments

When you forward an email that has attachments, Omniscio tries to deliver every attachment to Claude with the same fidelity as the chat composer — no setup required, no separate toggle. Images arrive as native vision content blocks, PDFs arrive as native document content blocks (also vision-rendered), and text/Office documents land in the session workdir with their paths prepended to the prompt. Anything that can't be delivered (oversized file, format the vision API doesn't accept, download failure) is silently dropped from the payload AND surfaced to Claude in a short "Note: N attachments could not be included:" line at the bottom of the email — so neither the user nor the agent silently loses information.

The three delivery routes match chat-attachments.md one-for-one — same partition logic, same Anthropic API content blocks, same workdir-save mechanics — so anything documented there about how Claude perceives a given file type holds for the email path too.

Attachment type What Claude sees Where the bytes go
Image (PNG / JPEG / GIF / WebP) image content block (base64 inline, vision) Inline only — not saved to workdir
PDF document content block (base64 inline, vision) Inline + saved to <workdir>/.claude/amc-attachments/<sessionId>/ so Claude can also Read / edit
Text doc (.md .txt .csv .json .html .xml .tsv .log .markdown) A line in the prompt prefix: "Please examine the following file(s): <path>" Saved to workdir; only the path is in the prompt
Office doc (.docx .xlsx .pptx + legacy .doc/.xls/.ppt, ODF .odt/.ods/.odp, .epub, .rtf) Markdown extracted in main via the anydoc reader, saved as <base>.md next to the original; that .md path is in the prompt The extracted .md lives in workdir; the original binary is not preserved (different from the chat path, which keeps both as chip metadata)

Caps and the per-attachment ceiling.

  • 30 MB per image / 32 MB per document — the same Anthropic vision API limits the chat composer enforces. Anything bigger is skipped with reason oversize_image or oversize_document.
  • 10 attachments per email — a hard cap to keep a single malformed email (most often an HTML newsletter with dozens of CID-embedded signature graphics, tracking pixels, and themed icons) from blowing up the prompt. When the inbound message exceeds the cap, Omniscio sorts by Content-Disposition first — explicit attachment parts win over inline parts, since the user almost certainly meant to forward the real payload rather than the email's chrome — then keeps the first 10. Everything past the cap is skipped with reason too_many_attachments.
  • Image format whitelist — the Anthropic vision API only accepts PNG, JPEG, GIF, and WebP. HEIC (iPhone default), SVG, BMP, TIFF, and AVIF are dropped at this layer with reason unsupported_image_format rather than rejected by the model after spawn. If you want Claude to look at a HEIC photo, convert it to JPEG or PNG before forwarding.
  • All office formats extracted — legacy binary Office (.doc / .xls / .ppt), OpenDocument (.odt / .ods / .odp), .epub, and .rtf now extract to Markdown via the on-device anydoc reader (the same engine + shared partition the chat path uses), not just the modern .docx / .xlsx / .pptx. A forwarded office file the reader can't parse surfaces as office_extract_failed (next bullet) rather than being dropped.
  • No-text-extracted Office files surface as office_extract_failed — the chip path on chat would keep the binary as a chip, but the email path has nowhere to surface a chip, so the skip note is the only signal.

What the agent sees when something is skipped. The session prompt ends with a literal note listing every skipped attachment, one per line, with the filename and a stable reason token:

Note: 3 attachments could not be included:
- big.png (oversize_image)
- old.doc (office_extract_failed)
- art.heic (unsupported_image_format)

So if a user forwards an email saying "look at the screenshot I'm attaching" and the screenshot was 50 MB, the agent will know to ask the user to re-send a smaller version rather than guess at what was missing.

The full set of skip reason tokens is: too_many_attachments, download_failed, not_carried_by_mail_pipeline, oversize_image, oversize_document, unsupported_image_format, unsupported_type, office_extract_failed, workdir_save_failed.

not_carried_by_mail_pipeline is the one token that is NOT about the sender. Every other reason means we could not use a file that reached us in full, or could not fetch it at all. This one means the file did arrive and its contents did not reach the session — either the pipeline dropped them, or it parked them somewhere this install could not retrieve them from. It is a distinct token, and it renders as a full sentence rather than the token, because an agent shown only download_failed reasonably concludes the sender forgot to attach the file and tells them so: on 2026-09-30 an agent told a customer her log zip "didn't come through" and asked her to send it again, when the pipeline had received it and discarded it. The note for this token says plainly that the sender DID attach it and instructs the agent not to ask for the same file again.

Large attachments are offloaded, not dropped. The parsed message reaches inboundEmail as one payload stored as one Firestore document, whose 1 MiB ceiling is far below a log bundle or a screenshot. The Cloudflare worker inlines only what comfortably fits and parks the rest in the amc-agent-email-attachments R2 bucket, which the desktop then fetches back over attachments.omnisciomail.com and feeds through the normal attachment pipeline — so a large file arrives, is saved to the session workdir or attached as a vision block, exactly like a small one. The object key is derived from data already on the queue row, so this needs no new field on the wire and an older install simply degrades to the token above. A not_carried_by_mail_pipeline skip on a large attachment therefore means the FETCH failed — the worker route was unreachable, the object had expired, or the install predates the feature. See the worker README.

One bad attachment never sinks the email. Each attachment is downloaded and processed independently — a 502 from AgentMail's CDN on attachment #3 surfaces as a single download_failed skip entry, and attachments #1, #2, #4… still flow through normally. The session still spawns; the email body still reaches Claude.

Troubleshooting

Symptom Cause Fix
Test button shows "Could not reach AgentMail service" API key missing or invalid Re-do step 2 — save the key in Settings → Email Inbound, or store it in the macOS Keychain / set AGENTMAIL_API_KEY.
Test button shows "401 / 403" Key is valid but doesn't own that inbox The key and inbox must be from the same AgentMail account. Re-copy the key from your AgentMail dashboard.
Email Inbound is on but nothing arrives Omniscio isn't running, or the polling task hasn't ticked yet Wait 30 seconds. Confirm Omniscio is open. Check the Omniscio log for [EmailInbound] lines.
Approved sender's email is dropped silently Subject doesn't include [MC:<token>] Either tell the sender to include it, or clear the Inbox Secret Token field to disable token gating.
forward_email automations fail with "AgentMail API key" error Same credential store; same key Same fix as the Test button — provision the key per step 2.
Key was rotated but Omniscio still uses the old one In-process cache holds it until the next 401/403 clears it Either restart Omniscio, or wait for the next AgentMail call to fail-then-retry with the new key.

What this does NOT cover

  • Existing-Gmail-inbox triage. That's a separate feature — see gmail-integration.md. Gmail integration uses your Google OAuth, not AgentMail.
  • Forwarded-newsletter digests. That's Email Summarizer, which uses the same AgentMail inbox but a different processing pipeline (a GPT-5.6 Luna summary on a thread by default, not a session spawn).
  • Outbound forward_email automations. They use the same API key, but the rule structure is documented in forward-email-transport.md.
  • AgentMail account / billing. Sign-up, plan, quota, and inbox management all happen at agentmail.to. Omniscio has no UI for any of it.

Last verified 2026-10-12