Document
A Document is a standard Salesforce object that stores binary files inside a folder-based hierarchy, used mainly to hold images referenced from HTML email templates, public Sites pages, and Visualforce markup.
Definition
A Document is a standard Salesforce object that stores binary files inside a folder-based hierarchy, used mainly to hold images referenced from HTML email templates, public Sites pages, and Visualforce markup. Documents predate Salesforce Files and rely on a separate sharing model where access is granted at the folder level rather than per record. Each Document record holds a Name, a folder assignment, a Body up to 5 MB, a description, a keyword field, and an IsPublic flag that controls whether the file can be streamed without a Salesforce session.
The object remains relevant because the modern Files framework cannot host an image that an external email client will fetch without authentication, and several rendering paths inside Visualforce and Sites still expect the legacy servlet URL. Administrators rarely create new Documents today, but every long-lived org carries hundreds of them tied to email templates and brand assets that nobody wants to break. Treat the object as legacy infrastructure: keep what works, audit what is public, and route new file storage to Files.
How the Document object actually works
Folder visibility, not record sharing
Documents skip the standard sharing model entirely. A user sees a Document only if they have access to its parent folder, and folder access is granted to All Internal Users, a specific public group, a role, or named users. There are no sharing rules, no manual shares, and no Apex sharing for Documents. The simplicity is the point. The trade-off is that you cannot grant access based on record ownership or criteria, which makes Documents a poor fit for anything user-specific.
The IsPublic flag and the servlet URL
Setting IsPublic to true exposes the Document body through a stable URL of the form /servlet/servlet.ImageServer?id=<DocumentId>&oid=<OrgId>. That URL works without a Salesforce login, which is why email templates rely on it: when a customer opens an email, their mail client fetches the logo without authenticating. The same property is also the security trap. Anyone with the URL can retrieve the body, and Salesforce will never know who downloaded it.
Documents versus Files versus Attachments
Three legacy file mechanisms still coexist. Attachments live on parent records and use record sharing. Files use the ContentDocument framework with its own sharing model based on libraries and explicit shares. Documents use folders. For new work, prefer Files: better collaboration, version history, and Lightning integration. Keep Documents where you already use them for email-template images and Sites assets, because there is no clean migration path that preserves the public URLs.
Storage quota and 5 MB body limit
Documents count against the Files storage allocation, not Data storage. Each Document body caps at 5 MB. Storage usage shows under Setup > Storage Usage with Documents listed separately. Deleting old Documents will not free Data storage, so do not chase that lever during a Data cleanup. The Files quota is generous, usually 10 GB plus 612 MB per user license, and most orgs never exceed it.
Why email templates still pin to Documents
When the rendering engine processes an HTML email template, it embeds the public Document URL directly in the outgoing message. The recipient mail client fetches the image from the servlet without any Salesforce credential, which is exactly what you need for logos and footer graphics. Files cannot do this because the ContentDocument download endpoints require an authenticated session or a public link with a token that expires.
Auditing public Documents
Run a periodic audit on Documents where IsPublic = true. Long-lived orgs accumulate dozens of these as users upload assets for one-off tests and forget to flip the flag back. A simple SOQL query returns the list: SELECT Id, Name, FolderId, LastModifiedDate FROM Document WHERE IsPublic = true. Review each, confirm it is intentionally exposed, and unmark anything that does not need public access.
Limitations that will not change
You cannot add custom fields, validation rules, triggers, record types, or list views to the Document object beyond what the basic folder browser offers. Reports built against Documents are not supported in the standard report builder. The object is closed to extension by design, reflecting its narrow remaining role. Treat anything you need beyond name, folder, and body as a signal to use Files instead.
Set up a Documents folder for email-template assets
Setting up a Documents folder for brand assets needs three things: a folder with the right visibility, the IsPublic flag set on each Document that will be embedded in an email, and a clear naming convention so future admins can find what was uploaded.
- Create the folder
Go to the Documents tab > Create New Folder. Name it Brand Assets or similar, and set Folder Access to Read Only for the audience that will browse it.
- Set folder visibility
Choose This folder is accessible by all users, or restrict to specific roles, groups, or users. Pick the broadest visibility appropriate, since Documents have no per-record sharing.
- Upload the Document
From the folder, click New Document. Enter a Name, an optional description, optional keywords, and upload the file. Keep the body under 5 MB.
- Mark it Externally Available
Check the Externally Available Image checkbox before saving. This sets IsPublic to true and unlocks the servlet URL for use in email templates and public Sites.
- Capture the public URL
Open the Document, right-click the image preview, and copy the image URL. The format is /servlet/servlet.ImageServer?id=<DocumentId>&oid=<OrgId>. Save this in your email-template reference doc.
- Reference it from an email template
In the HTML email template, use <img src="https://<your-instance>.salesforce.com/servlet/servlet.ImageServer?id=...&oid=...">. Test by sending the template to an external address and confirming the image renders without a login prompt.
- Document the asset in a brand register
Track Document Name, URL, intended use, and review date in a separate sheet or wiki. Without this register, future admins will be afraid to delete anything because they cannot tell what is still in use.
Sets IsPublic = true. Required for any Document referenced from an email template that goes to external recipients.
Sets IsInternalUseOnly = true. Indicates the Document is not licensed for external distribution. Useful as a metadata flag; it does not block access.
Comma-separated tags searchable from the Documents tab. The only built-in mechanism for organizing Documents across folders.
Free text shown on the Document detail page. Use it to record intended use and the email template that references the file.
Read Only or Read/Write at the folder level. There is no per-Document override, so plan folder structure around access groups, not topics.
- The Externally Available Image checkbox is the same flag as IsPublic in the API. Forgetting to check it is the single most common reason an email template renders a broken image for external recipients.
- The servlet URL hard-codes the Document ID. If you delete and re-upload a logo, every email template referencing the old ID breaks. Update the body in place using the Replace Document button instead.
- Documents cannot be migrated to Files while preserving the public URL. Plan to keep email-template assets on the Document object for the lifetime of those templates.
- Folder visibility cannot be set per record. If one Document in a folder needs broader access, you have to move it to a more permissive folder, not adjust the Document directly.
- Body size caps at 5 MB. Large images need to be optimized before upload, and the Documents tab has no built-in image-optimization step, so do it in your image editor first.
Trust & references
Straight from the source - Salesforce's reference material on Document.
- Document in Object Reference for the Salesforce PlatformSalesforce Developer Documentation
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.
Discussion
Loading discussion…