Email Attachments
Email Attachments are files attached to inbound or outbound email messages handled by Salesforce, stored either as ContentDocument records (under Enhanced Email) or as Attachment records (legacy mode).
Definition
Email Attachments are files attached to inbound or outbound email messages handled by Salesforce, stored either as ContentDocument records (under Enhanced Email) or as Attachment records (legacy mode). The platform handles attachments differently depending on whether the email was sent from a Salesforce-native channel (List Email, Email-to-Case, Outlook/Gmail integration), received through Email Services, or imported from a connected mail client. Across all these paths, the attachment is preserved as a file linked to the relevant EmailMessage record, and remains accessible from the Activity Timeline on related records.
Storage of email attachments counts against the org's Files allocation, not Data storage. Default maximum attachment size depends on the channel: outbound List Email sends up to 25 MB per email, Email-to-Case ingestion handles up to 25 MB per inbound message, and Apex email handlers cap at 25 MB per inbound message split across all attachments. The platform automatically MIME-decodes attachments on inbound mail and re-encodes on outbound, so administrators rarely need to deal with the encoding directly.
How Salesforce stores and limits email attachments
Enhanced Email versus legacy storage
Enhanced Email, on by default since 2017, stores email as EmailMessage records and attachments as ContentDocument files. Legacy mode stored email as Activity records and attachments as Attachment records on those activities. The Enhanced Email shift was the single largest change to email handling in the past decade, because it unified inbound and outbound email under a single object model and made attachments first-class Files instead of legacy Attachments. Orgs created after 2017 will only see Enhanced Email; older orgs may have a mix.
How attachments are linked to records
Each attachment under Enhanced Email is a ContentDocument with a ContentDocumentLink to the parent EmailMessage. The EmailMessage in turn links to the Case, Lead, Contact, or Opportunity it was filed against, so the attachment appears under the Files related list of that record. The chain is EmailMessage > ContentDocumentLink > ContentDocument > ContentVersion (the binary). Querying any of these objects returns the attachment metadata; the binary is fetched separately from the ContentVersion record.
Inbound attachment limits
Email Services and Email-to-Case accept up to 25 MB per inbound message in total attachment size, with individual attachments capped at the same 25 MB. Messages exceeding the limit are bounced with a delivery failure notification to the sender. The limit is fixed and cannot be raised through configuration. Workflows that need larger files must use a different channel (a file upload portal, a shared drive link in the email body, or a Files request link).
Outbound attachment limits
List Email sends cap at 10 MB per attachment and 25 MB total per email. Single-email Send actions through the standard Email composer cap at the same limit. The standard sender enforces this client-side before the API call; over-the-limit attachments produce a visible error to the user. The cap is platform-level, not configurable.
Apex email handlers
Custom Apex email handlers (classes implementing the Messaging.InboundEmailHandler interface) receive an InboundEmail object that includes binaryAttachments and textAttachments arrays. The handler is responsible for converting these into ContentVersion or Attachment records, depending on whether the target record uses Enhanced Email storage. The 25 MB total cap applies; the handler will not receive attachments that would push the message past the limit.
Outlook and Gmail integration
The Outlook and Gmail integrations log emails to Salesforce records with their attachments. Attachments are uploaded as Files (ContentDocument), with a default max size that depends on the connector. The integration runs in the user's mail client, so the local mail client's own attachment limits also apply. Workflows that depend on large attachments from these channels often fail at the mail client boundary before reaching Salesforce.
Auditing and cleanup
Email attachments are a top-three contributor to Files storage growth in long-running orgs. Audit periodically with a SOQL query against ContentVersion filtered to documents linked through EmailMessage. Identify large attachments older than your retention window and delete or archive them. The platform does not auto-purge email attachments; without a cleanup job, storage grows indefinitely with email volume.
Configure email attachment handling end to end
Email attachment behavior is a mix of org settings, channel limits, and storage hygiene. The steps below cover the rollout of attachment handling for a new use case from initial configuration to long-term storage management.
- Confirm Enhanced Email is on
Setup > Email > Enhanced Email. Check the activation status. If off and the org predates 2017, plan the activation as a separate project; it changes the underlying data model for all email.
- Identify the channels
List which channels will produce attachments: Email-to-Case, Apex email handlers, List Email, Outlook/Gmail integration. Each has its own limits and storage path.
- Test inbound limits
Send a test message with attachments of varying sizes to confirm the 25 MB cap behavior. Verify the bounce message format so support knows how to triage user complaints.
- Test outbound limits
Compose a test email with attachments exceeding 10 MB per file and confirm the error appears in the composer. Train end users on the limits before rolling out.
- Configure storage audit query
Build a SOQL query: SELECT Id, Title, ContentSize FROM ContentVersion WHERE FirstPublishLocationId IN (SELECT Id FROM EmailMessage) ORDER BY ContentSize DESC. Save it as a scheduled report.
- Set retention rules
Define how long email attachments are retained. Common rules: 90 days for Case attachments, 1 year for Opportunity attachments, indefinite for compliance objects. Document the rule clearly.
- Schedule the cleanup
Build an Apex batch or scheduled Flow that deletes ContentVersion records older than the retention window. Test in sandbox; production deletes are irreversible after the Recycle Bin window.
Default modern mode. Email attachments stored as ContentDocument. Recommended for any new org.
Pre-2017 mode. Email attachments stored as Attachment on the Activity. Migrate to Enhanced Email if still active.
Setting on the Email-to-Case service that controls which Case the attachment lands on. Affects how Files appear in the Case Files related list.
Custom code that decides where binaryAttachments and textAttachments are saved. Common pattern: save as ContentVersion linked to the parent record.
Per-user setting on the integration. Controls whether attachments are uploaded to Salesforce with the logged email.
- The 25 MB cap is per inbound message total, not per attachment. Five 6 MB files in one message bounces; one 24 MB file is fine.
- Apex handlers receive binaryAttachments and textAttachments separately. Code that only processes the first silently drops .txt and .csv attachments.
- Enhanced Email cannot be turned off once activated. Plan the activation carefully because the underlying storage model changes permanently.
- Outlook/Gmail integration applies the user's mail client size limit before Salesforce sees the message. Users hitting issues may need to check their mail client first.
- Storage cleanup deletes ContentVersion, which deletes the file. There is no easy way to selectively delete email attachments; the cleanup must filter accurately to avoid deleting other Files.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is the primary benefit of Email Attachments for Salesforce administrators?
Q2. In which area of Salesforce would you typically find Email Attachments?
Q3. Can a Salesforce admin configure Email Attachments without writing code?
Discussion
Loading discussion…