Email Message
An Email Message is the EmailMessage object in Salesforce, the record that stores every individual email sent to or from a Case or other supported record.
Definition
An Email Message is the EmailMessage object in Salesforce, the record that stores every individual email sent to or from a Case or other supported record. Each EmailMessage holds the From, To, Cc, and Bcc addresses, the subject, the HTML and plain-text bodies, attachments, and threading metadata. The object is a child of Case through the ParentId field, so one Case can hold the full back-and-forth of a support conversation.
EmailMessage is the queryable, reportable form of email inside Salesforce. It is different from an Email Template, which is the reusable content blueprint, and from an Email Alert, which is the automation that triggers a send. Email-to-Case, the Lightning Email Composer in the Case feed, automated case responses, and Apex all create EmailMessage records. When an agent replies, Salesforce writes an EmailMessage with a Sent status. When the customer answers back, the inbound mail lands as another EmailMessage on the same Case.
How EmailMessage records flow through a support conversation
The object model: ParentId, RelatedToId, and EmailMessageRelation
Every EmailMessage links to a parent record through the ParentId lookup, and on a service org that parent is almost always a Case. One Case can have many EmailMessage children, which is what lets the Case feed show a threaded history. The RelatedToId field can tie the email to a separate business record, such as an Account or Opportunity, when the email is not strictly a case reply. A companion object, EmailMessageRelation, exists in API version 37.0 and later. It records which Contacts, Leads, or Users sat on the From, To, Cc, or Bcc line of each message, so you can report on who actually received an email rather than parsing raw address strings. This split matters for reporting. ParentId answers which Case an email belongs to, RelatedToId answers what else it touches, and EmailMessageRelation answers who was on it. Understanding the three together stops the common mistake of treating the plain ToAddress text field as if it were a clean list of recipient records.
Status values and the Incoming flag
The Status field on EmailMessage is stored as a number even though the interface shows a label. New is 0, Read is 1, Replied is 2, Sent is 3, Forwarded is 4, and Draft is 5. A draft email created through the sendEmailMessage() call sits at status 5 until it is actually delivered. The Incoming boolean separates inbound mail from outbound. When Incoming is true, a customer sent the message into Salesforce. When it is false, an agent or an automation sent it out. These two fields carry most of the analytical weight on the object. A first-response report filters for the earliest outbound EmailMessage on a Case. An unanswered-email report looks for Cases whose most recent EmailMessage has Incoming set to true. Because Status is numeric under the hood, SOQL filters work against the number, so a query for sent mail uses Status equals 3. Knowing the codes saves you from guessing why a label filter behaves oddly in Apex.
Email-to-Case as the inbound source
Email-to-Case is the feature that turns inbound email into Cases and their EmailMessage children. A customer sends mail to an address like support@yourcompany.com. Salesforce either opens a new Case or, if it recognizes the conversation, attaches a fresh EmailMessage to the Case that already exists. You configure it in Setup under Email-to-Case, where you define each routing address and decide what default values, such as origin or priority, land on the new Case. The standard version routes mail through Salesforce-hosted forwarding. Email-to-Case Premium, a paid add-on, adds bounce handling, signature stripping, and capacity for very high inbound volume. The Trailhead exercise for setting it up walks through turning on the feature, connecting a support address, choosing case defaults, and verifying the routing address by clicking a confirmation email. For teams receiving thousands of messages a day, the routing rules and default field mappings decide how clean the resulting Case data is.
Threading: how replies find the right Case
Threading is the logic that attaches a customer reply to the correct existing Case instead of opening a duplicate. Older Email-to-Case relied on a Reference ID, an opaque token placed in the email subject. If a customer or their mail system removed that token, the reply could not be matched and a second Case appeared. Salesforce moved to Lightning threading, which combines header-based matching with token matching for a more reliable and more secure result. From Summer 20 onward, Salesforce automatically saves the Message-ID of outbound Case-feed emails, which feeds the header side of the match. Header-based threading reads standard email headers like Message-ID, In-Reply-To, and References, the same plumbing every mail client already uses to group a thread. The practical lesson is to avoid stripping or rewriting subject lines on the customer side and to confirm that any newsletter or marketing platform in the loop preserves headers. Broken threading is the single most common cause of duplicate Cases, so it is worth auditing the inbound addresses that feed your org.
Attachments, body fields, and external visibility
An EmailMessage carries both an HtmlBody and a TextBody, and the platform shows whichever fits the channel or the reader. The HasAttachment flag gives you a fast way to filter messages that carried files without joining to the attachment records themselves. Attachments are stored as Salesforce Files, linked to the EmailMessage, and outbound mail respects the standard email size limit. Very large inbound attachments may be stripped or the message rejected, depending on how Email-to-Case is set up. The IsExternallyVisible field controls whether a customer can see a given message in an Experience Cloud help center or customer portal. An internal note an agent never meant to share can be kept hidden, while the genuine reply stays visible. Getting this flag right protects against leaking internal commentary into a customer-facing thread. When you build automation that creates EmailMessage records directly, set the body fields, the parent, and the visibility flag deliberately, because a record written by Apex does not inherit the safe defaults that the Lightning composer applies for you.
Reporting and the agent reply flow
From a Case, an agent opens the Lightning Email Composer in the feed, picks Reply or Reply All, and the composer pre-fills the recipient and the threading detail. Templates and Quick Text speed up the body, and sending writes a new EmailMessage with Sent status tied to the Case through ParentId. Because every send and receive becomes a row, EmailMessage is a rich source for service analytics. The standard Email Messages report type joins EmailMessage to Case so you can blend email facts with case facts. Common questions it answers include first-response time, email volume per agent per day, average messages per Case, and the busiest inbound sender domains. A subtle gap is that the standard Case metrics do not surface time since the last customer reply, which is often the most actionable service signal. Many teams close it with a Flow that stamps a Last Inbound Email Date on the Case whenever a new inbound EmailMessage arrives, then drive alerts and dashboards off that field.
Set up Email-to-Case so EmailMessage records start flowing
You do not create EmailMessage records by hand. They appear when Email-to-Case captures inbound mail and when agents reply from the Case feed. To make that happen, turn on Email-to-Case and connect a support address. These steps follow the Salesforce setup flow.
- Turn on Email-to-Case
In Setup, search for Email-to-Case, open it, and enable the feature. Confirm when prompted. This activates the engine that converts inbound mail into Cases and EmailMessage records.
- Connect a support email address
Open the routing address manager and add the address customers will write to, such as support@yourcompany.com. Choose your email provider, then verify the address by clicking the confirmation email Salesforce sends.
- Set case defaults
Decide which default values, such as Case Origin and Priority, get stamped on Cases created from this address. Clean defaults here save manual cleanup later and keep your reporting consistent.
- Enable the Email action in the Case feed
Confirm the Email quick action is on the Case feed layout so agents can reply. Each reply they send writes an outbound EmailMessage linked to the Case through ParentId.
The inbound address customers email. Each one can carry its own default Case field values and its own forwarding setup.
The header-plus-token matching that attaches replies to the right Case. Keep it on so customer answers thread cleanly instead of spawning duplicates.
A paid add-on for bounce handling, signature stripping, and very high inbound volume. Worth evaluating once daily email counts climb into the thousands.
The IsExternallyVisible flag on each message. Controls whether a customer sees a message in an Experience Cloud help center or portal.
- Broken threading is the top cause of duplicate Cases. If a customer or a relay strips the subject token or rewrites headers, replies cannot match and a second Case opens.
- Status is stored as a number, not text. In SOQL or Apex, filter sent mail with Status equals 3, not the word Sent, to avoid surprises.
- Records you create in Apex do not inherit the composer defaults. Set ParentId, the body fields, Incoming, and IsExternallyVisible explicitly or the message may render or route incorrectly.
Prefer this walkthrough as its own page? How to Email Message in Salesforce, step by step
Trust & references
Cross-checked against the following references.
Straight from the source - Salesforce's reference material on Email Message.
Hands-on resources to go deeper on Email Message.
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…