> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Attachment handling ## Overview By default, your AI Agent hands off all emails that have attachments to human agents. You can change this behavior for each inbox: keep the default, or let your AI Agent reply to the email body — either discarding the attachment, or keeping it in case the conversation is later handed off. ## Limitations AI Agents can send up to 30 MB in files with a [Handoff](/docs/handoffs). Different email clients and receiving agent platforms have their own limitations on file sizes (e.g., Gmail has a limit of 25 MB), so if a customer tries to send a large attachment, it might not get delivered to your AI Agent or passed on to your agent platform. ## Use cases Attachment handling is useful in the following scenarios: * **Escalating emails with attachments**: When end users send emails with attachments, your Email AI Agent can [hand off](/docs/handoffs) these conversations to human agents, ensuring attachments are available for review. * **Passing files to support platforms**: When handing off conversations to your agent platform, attachments are passed through so human agents can access the files end users sent. * **Reviewing customer-submitted documents**: Human agents can access documents, images, spreadsheets, and other files that end users attach to their email inquiries. ## Capabilities & configuration Your AI Agent can pass email attachments to human agents through supported [Handoff](/docs/handoffs) blocks. Attachments are securely saved upon receipt and automatically deleted after 7 days. ### Choose how each inbox handles attachments Each inbox has its own **Attachment handling** setting that controls what happens when that inbox receives an email with an attachment. **To change an inbox's attachment handling:** 1. On the Ada dashboard, go to **Config > CHANNELS > Email**. 2. Click the inbox you want to configure. 3. Under **Attachment handling**, select an option, then click **Save**: ![](/_fern-img/78548a180b3fb92ac2a4ef2d40bfc1505e6c410974d0f5d9a66fe9171b3af4a8.webp) | Option | Behavior | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Hand off to a human (default)** | Your AI Agent doesn't answer the email. The conversation is handed off to a human agent, and every accepted attachment goes with it. | | **AI Agent replies without the attachment** | Your AI Agent replies to the email text. The attachment is discarded, so no one receives it. | | **AI Agent replies using the attachment** | Your AI Agent reads up to 3 [image](/docs/other/images) attachments and replies. Every accepted attachment is kept and included if the conversation is later handed off. | An attachment with an unsupported file type is rejected when the email arrives. If the conversation is handed off, the human agent gets a note that names the skipped file. See [Accepted file types](#accepted-file-types) and [Restricted file handling](#restricted-file-handling). The setting applies per inbox, so different inboxes on the same AI Agent can handle attachments differently. Small inline signature images in an email aren't treated as attachments — emails whose only image is a signature are processed as regular text in every mode. Files sent through the [Email API](/docs/channels/email/email-configuration/implementation-method#api) follow the same setting. They're never treated as signature images, so a small or transparent screenshot counts as an attachment. Your AI Agent reads image attachments only on the **AI Agent replies using the attachment** setting. See [Images](/docs/other/images) for the formats it reads and which images it withholds. A HEIC or HEIF image that the Agent reads is kept as its JPEG conversion, so human agents receive a `.jpg` on handoff. ### Supported Handoff blocks Email attachments can be passed on the following [Handoff](/docs/handoffs) blocks: * [Zendesk Ticketing](/docs/channels/email/email-configuration/email-handoffs#zendesk-ticketing) block * [Salesforce](/docs/channels/email/email-configuration/email-handoffs#salesforce) block * [Email](/docs/channels/email/email-configuration/email-handoffs#email) block ### Accepted file types Your AI Agent can pass along files with the following extensions to agents:
* `.avif` * `.csv` * `.doc` * `.docx` * `.eml` * `.gif` * `.heic` * `.heif` * `.jpeg` * `.jpg` * `.keynote` * `.log` * `.m4a` * `.m4v` * `.mov` * `.mp3` * `.mp4` * `.mp4a` * `.mpeg` * `.mpg` * `.numbers` * `.pages` * `.pdf` * `.png` * `.ppt` * `.pptx` * `.svg` * `.txt` * `.wav` * `.xls` * `.xlsx` * `.zip`
### Restricted file handling If your AI Agent restricts a file from being passed through to your agent platform, either due to its size or an unsupported file extension, it adds a comment to the ticket explaining which file(s) it restricted, and why. ![](/_fern-img/3389eb5c2c03c3ebec93b36f99028d4d370f0313c3edae850d90049b91f9530d.webp) ## Quick start Enable attachment handling in your [Handoff](/docs/handoffs) block. For detailed instructions, see [Implementation & usage](#implementation--usage). Configure your [Handoff](/docs/handoffs) block to pass email attachments to your agent platform. ## Implementation & usage Configure your [Handoff](/docs/handoffs) block to pass attachments to your agent platform. **To set up attachment handling:** 1. Add the **File Data Token** field from the **Optional Inputs** dropdown in your [Handoff](/docs/handoffs) block. 2. In the **File Data Token** field, add the **email\_attachments** variable to ensure that your AI Agent can pass any attachments to your agent platform. ![](/_fern-img/635bc3aafec27ad243f56c4d9dab1dd1971b61aa3b08731cc2d0ebe868578c04.webp) ### Viewing attachments in Convos In the **Convos** view, you can see if customers sent attachments by looking in the conversation metadata. If the `email_has_attachments` metavariable is True, the conversation has attachments stored on it. On inboxes set to discard attachments, the variable is False even when the customer's email included an attachment, because the file wasn't kept. ## Related features Explore additional Email Handoff and configuration options. * [Email handoffs](/docs/channels/email/email-configuration/email-handoffs): Configure Handoff blocks for your Email channel. * [Handoffs](/docs/handoffs): Learn about Handoff capabilities across all channels. * [Conversations](/docs/optimization/conversations): View attachment metadata in conversation details. * [Images](/docs/other/images): Learn how your AI Agent reads image attachments. --- Have any questions? Contact your Ada team, or email us at [](mailto:help@ada.cx?subject=Help%20Docs%20inquiry).