Your Salesforce Email Attachments Are Failing Silently. Here’s What’s Actually Going Wrong.

Master Salesforce email attachments. Understand size limits, Base64 encoding overhead, Files vs Attachments storage, template attachment methods, Flow Builder automation, and how to send large files without errors.

Sending an email with a file from Salesforce sounds simple—until a 10 MB PDF silently becomes 13.3 MB after encoding and the entire message fails without warning. Salesforce email attachments are governed by size limits, encoding overhead, storage architecture choices, and sending method constraints that most teams discover only after emails stop delivering. This guide covers every attachment limitation, explains when to use Files vs Attachments vs links, and shows how to automate file delivery at scale from inside Salesforce email.

Email Attachment Size Limits by Sending Method

Salesforce enforces a 25 MB total email size limit for outbound messages—including the body, headers, encoding overhead, and all attachments combined. Individual files attached to emails in Lightning Experience are capped at 10 attachments per message, while Classic allows more. Inbound Email-to-Case messages accept up to 35 MB total. The Salesforce email attachment limits documentation details the per-file cap of 5 MB when attachments are stored as Salesforce records.

The critical detail most teams miss: Base64 encoding inflates every attachment by approximately 33%. A 10 MB file on disk becomes roughly 13.3 MB in the email payload, consuming over half the 25 MB budget before you add the HTML body or signature. Calculate true email size by multiplying visible attachment size by 1.33, then adding body and header weight. For a detailed breakdown of every limit by context, see our attachment size limit guide.

Salesforce Files vs Legacy Attachments Object

Salesforce maintains two distinct storage systems for file data. The legacy Attachment object (available in Classic) stores files directly on parent records with a 25 MB per-file limit. The modern Salesforce Files system uses ContentDocument, ContentVersion, and ContentDocumentLink objects, supporting files up to 2 GB in Lightning Experience with versioning, sharing controls, and preview capabilities.

For email purposes, both systems work—but Files offers significant advantages. Files can be shared across records, reused in multiple templates, and linked without duplication. Legacy Attachments create a separate copy per record, consuming storage faster. Salesforce is actively migrating orgs toward Files; new implementations should use ContentVersion exclusively. Configure default behavior under Setup → Email → Email Attachments to control whether files are sent as direct attachments or downloadable links.

Attaching Files to Email Templates

Lightning Email Templates support file attachments through the template builder—upload files or select from existing Salesforce Files. Classic email templates (Text, HTML, Visualforce) also support attachments, though Visualforce templates require Apex to attach files programmatically. Template-attached files are sent with every email using that template, making them ideal for standard documents like brochures, price lists, or terms of service that don’t change per recipient.

For dynamic attachments—where each recipient receives a different file based on their record—native templates fall short. You need either Apex code to query ContentVersion records and attach them at send time, or a platform like MassMailer that supports dynamic attachments from related objects natively. Dynamic attachment is essential for use cases like sending personalized invoices, contracts, or proposals linked to Opportunity or Account records. For template creation details, see our Lightning email templates guide.

Automating Attachments with Flow Builder and Apex

Flow Builder’s Send Email action supports attachments via the Attachment ID or Attachment ID Collection fields, which accept ContentVersion IDs. Create a Get Records element to query ContentVersion where FirstPublishLocationId matches your record, then pass the resulting IDs to the Send Email action. Note that using attachment fields in Flow switches the email from the workflow email pool to the single email limit, which has a separate 5,000/day cap.

Apex provides more control through the SingleEmailMessage class’s setFileAttachments() and setEntityAttachments() methods. setFileAttachments() accepts in-memory blobs (useful for dynamically generated PDFs), while setEntityAttachments() references existing ContentVersion IDs. Both methods count against the daily sending limit. For high-volume sends with attachments, batch Apex with staggered scheduling prevents limit exhaustion. See our email automation overview for workflow design patterns.

Sending Files as Links vs Direct Attachments

Salesforce offers three delivery settings under Setup → Email → Email Attachments: always send as links, send as attachments up to 3 MB (links if larger), or send as attachments up to the full email size limit. Links reduce email payload size and eliminate delivery failures from oversized messages, but require recipients to click through to Salesforce to download, which may fail if they lack access.

Direct attachments ensure immediate access but consume more bandwidth, inflate email size, and count against storage when duplicated per recipient record. For bulk email campaigns with attachments, links are strongly recommended—a 5 MB attachment sent to 1,000 recipients creates 5 GB of duplicated storage. Alternatively, use Salesforce Files shareable links that work without authentication, or platforms like MassMailer that handle large file delivery without storage duplication.

Storage Impact and Org Capacity Planning

Every email attachment stored in Salesforce—whether as a File or legacy Attachment—consumes file storage quota. Enterprise Edition provides 10 GB base plus 2 GB per user license. When Email-to-Salesforce or email logging is enabled, inbound attachments are duplicated to each matched record, rapidly consuming capacity. A single 5 MB attachment matched to three records becomes 15 MB of storage.

Monitor consumption under Setup → Storage Usage and audit large files regularly. Implement retention policies to archive or delete attachments older than your compliance window. For teams sending file-heavy emails at scale, external document management through MassMailer Docs offloads storage while maintaining full tracking visibility for opens, clicks, and downloads directly on Salesforce records.

Troubleshooting Common Attachment Errors

The most frequent attachment failure is “Email size exceeds maximum allowed size”—almost always caused by encoding overhead. Multiply your total attachment size by 1.33 and add 50–100 KB for headers and body to estimate true payload size. Other common errors: “Maximum number of email attachments exceeded” (Lightning caps at 10 files), “INVALID_ID_FIELD” when passing an Attachment ID instead of a ContentVersion ID to Flow, and silent failures when sending to recipients with Email Opt Out enabled.

Test attachment sends in the sandbox before production, especially for automated Flows. Log delivery results through email logs to identify failures that the UI doesn’t surface. If errors persist, check that the sending user has Read access to the ContentVersion record and that the file hasn’t been archived. For systematic error diagnosis, see our email log errors guide.

Scalable Attachments with Native Salesforce Tools

Native Salesforce attachment workflows break at scale: size limits block large files, storage duplicates inflate costs, dynamic per-recipient attachments require custom Apex, and mass email doesn’t support attachments at all in its standard implementation. Teams sending proposals, contracts, reports, or marketing materials need a solution that works within Salesforce without these constraints.

MassMailer eliminates every native limitation. Attach files of any type directly from Salesforce Files, Documents, Attachments, or your device. Dynamically attach record-specific files so each recipient gets the document tied to their Account or Opportunity. Reuse attachments across templates and campaigns without storage duplication. Track whether attachments were opened and downloaded through native email reporting and campaign performance tracking—all 100% inside Salesforce.

Struggling with attachment size limits, storage bloat, or manual file handling? MassMailer lets you attach any file to any email from any Salesforce object—dynamically, at scale, with full download tracking. No Apex code. No storage duplication. No limits. Schedule a free demo to see attachment automation in action →

Key Takeaways

• Salesforce enforces a 25 MB total email size limit—Base64 encoding inflates attachments by 33%, so a 10 MB file actually consumes 13.3 MB of that budget.
• Use Salesforce Files (ContentVersion) instead of legacy Attachments for versioning, sharing, and 2 GB storage per file in Lightning Experience.
• Flow Builder supports attachments via ContentVersion IDs, but using them switches the email to the single email limit pool—plan capacity accordingly.
• Configure Email Attachment settings to send as links for bulk campaigns to prevent storage duplication and delivery failures from oversized messages.
• Every stored attachment consumes file storage quota—duplicated attachments from email logging can rapidly exhaust org capacity without monitoring.
• Native mass email doesn’t support attachments—dynamic, per-recipient file delivery at scale requires either custom Apex or a native platform like MassMailer.