The attachment filename that breaks your mail pipeline
Unicode, NBSP, and Outlook-style filenames collide with object storage keys. Sanitize before you store—learned the hard way in mail pipelines for agents.
Discuss this post in AI
Send a pre-filled prompt to ChatGPT, Claude, Gemini, or Perplexity — get a summary, ask follow-ups, or compare ideas from this guide.
Mail pipelines for agents look simple until the first real attachment arrives. A client sends a PDF whose name contains a non-breaking space. Outlook encodes a long UTF-8 name that your logger prints fine but your object key rejects. A Mac user uploads отчёт.pdf and a downstream regex written for ASCII quietly drops the file. The agent then swears the attachment never existed, and a human spends the afternoon reconstructing MIME by hand.
What actually breaks
Object stores and file systems disagree about allowed characters, length, and normalization. Email clients disagree about encoding of the filename parameter versus the name you see in the UI. MIME can offer multiple filename* sections. Copying the “display name” straight into a storage key is an incident waiting for a busy Monday when three clients send similarly named files in one thread.
We have seen pipelines fail on NBSP, RTL marks, combining characters, path separators embedded in names, and trailing dots or spaces that Windows tolerates in display but storage APIs do not. None of this is exotic once agents process mail at volume. It is ordinary internet mail meeting ordinary storage constraints.
Sanitize before store
Treat the original filename as untrusted metadata. Generate an internal object key from a UUID or content hash. Persist the original name separately as display metadata after NFC normalization and stripping of control characters. Replace NBSP with a normal space for display if you must show something human. Reject or quarantine path separators and empty names. Cap length before the key hits the storage API.
Do the sanitization in one shared library used by every ingest path—webhook, IMAP poller, or Agent Inbox connector—so Neuro OS roles never each invent a slightly different cleaner that fails on a different edge case.
Preserve forensics
When a human asks “what was the file called?,” you need the original bytes of the name as received, the sanitized display form, and the storage key. Log all three. If malware scanning renames or rejects a file, keep the reason next to the message id. Agents should cite the storage key in memory, not a fragile path built from the raw filename that may not round-trip.
Test with hostile fixtures
Build a fixture set: NBSP, Cyrillic, CJK, emoji, 200-character names, nested encoded words, duplicate names in one message, and missing filenames. Run them in CI against the ingest function. Add a case whenever production surprises you. Treat filename bugs as product bugs, not as “email is messy” folklore.
Product consequence
An AI accountant or ops role that “loses” attachments is not a model failure; it is an engineering boundary failure. Fix the boundary once. Agent Inbox can deliver the MIME. Your pipeline must make the bytes addressable. Sanitize early, store immutably, display carefully—and keep Ask on any outbound that forwards those attachments externally so a bad name never becomes a bad send without a human glance.
Operator playbook when a file “vanishes”
When an agent reports a missing attachment, operators should check quarantine, sanitizer rejects, and storage key mapping before blaming the model. Give them a single debug view: message id, original name bytes, sanitized display name, storage key, and scanner verdict. Faster incident response is part of making mail pipelines for agents trustworthy in production.
Agent Inbox gives each role a mailbox people can reply to, with forwarding into Neuro OS when a human must see the thread. Outbound mail defaults to Ask. Run the role on Neuro OS. To scope the first inbox, get started.