EmailMessage

Represents an email in Salesforce.

Supported Calls

create(), delete(), describeLayout(), describeSObjects(), getDeleted(), getUpdated(), query(), retrieve(), search(), undelete(), update(), upsert()

Special Access Rules

EmailMessage is only available for orgs that use Email-to-Case or Enhanced Email, which is automatically enabled for most customers.

To use reply and forward functionality, FromAddress must specify an email address that exists in EmailMessageRelation, with a RelationType of FromAddress.

The Status field is mostly read-only. You can change the status only from New to Read.

The HtmlBody and RelatedToId fields are supported in Classic list views but not in Lightning list views. In related lists and search results in Lightning Experience, these fields either don’t appear, show blank values, or result in an error.

update() is supported when an email record is in Draft status, and IsPrivateDraft is false. It’s also supported if the email status is Draft, IsPrivateDraft is true, and CreatedBy is associated with the current user. When the email record isn’t in Draft status, the IsExternallyVisible field and custom fields only can be updated.

Set the Update Email Messages user permission for users, such as an Automated Case User, who run automated processes that modify email message-related records. With the Update Email Message permission set, users’ processes can modify EmailMessageRelation and ContentDocumentLink records that are related to an email message that isn’t in Draft status. Don’t set this user permission for other users.

Access to an email message depends on the associated object. The user who created the email is specified in CreatedById and always has access, unless that user is a guest user. Guest users have read access if the message is marked as IsExternallyVisible.

The object that’s used to determine access differs for Email-to-Case and Enhanced Email.

  • Email-to-Case—When Email-to-Case is enabled and the email is Case-based (the ParentId field is Case), access depends on the user’s access to the related Case record. If the email message is a draft, only the user in the CreatedById field or users with the Modify All Data permission can access it.
  • Enhanced Email—Access is activity-based. The ActivityId field specifies an associated Task record. You can control access to activity-based objects with the Access Activities permission. Users with the Modify All Data permission can also access the message.

When you use the API to insert EmailMessage records in bulk, the same access rules apply: access is based on cases in ParentId fields or by tasks in ActivityId fields. When inserting a single record, set the CreatedById field to the user performing the operation or leave it blank.

Fields

Field Details
ActivityId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
Description
ID of the activity that is associated with the email. Usually represents an open task that is created for the case owner when a new unread email message is received. ActivityId can only be specified for emails on cases. It’s auto-created for other entities.
AttachmentIds
Type
string
Properties
Create, Nillable, Update
Description
A comma-separated list of email attachments. This is used by the Send Email quick action when you use Salesforce Classic email templates. Maximum length is 32, 768 characters.
AutomationType
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort
Description
A picklist value that determines if an outgoing email was manually created or AI-generated.
Possible values are:
  • AiAssisted–Email is AI-generated, but sent by human.
  • AiAutomated–Email is generated and sent by AI.
  • Null–Email is created and sent by human.
BccAddress
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
A string array of email addresses for recipients who were sent a visually impaired carbon copy of the email message. Include only email addresses that aren’t associated with Contact, Lead, or User records in Salesforce. If the recipient is a contact, lead, or user, add their ID to the BccIds field instead of adding their email address to the BccAddress field. When adding their ID, the email message is automatically associated with the contact, lead, or user. For an Experience Cloud site user who isn’t the sender of the email, this field returns null.
You can’t send emails unless there’s at least one recipient.
BccIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for contacts, leads, and users who were sent a visually impaired carbon copy of the email message. Each ID is linked to an EmailMessageRelation record, which represents the relationship between an email message and a Contact, Lead, or User record. For an Experience Cloud site user who isn’t the sender of the email, this list is empty.

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

CcAddress
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
A string array of email addresses for recipients who were sent a carbon copy of the email message. Include only email addresses that aren’t associated with Contact, Lead, or User records in Salesforce. If the recipient is a contact, lead, or user, add their ID to the CcIds field instead of adding their email address to the CcAddress field. Then the email message is automatically associated with the contact, lead, or user.
You can’t send emails unless there’s at least one recipient.
CcIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for contacts, leads, and users who were sent a carbon copy of the email message. Each ID is linked to an EmailMessageRelation record, which represents the relationship between an email message and a Contact, Lead, or User record.

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

ClientThreadIdentifier
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
A value used by third-party email clients to identify which thread an email belongs to. See Email-to-Case Threading for more information.

Available in API versions 56.0 and later.

ContentDocumentIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for content documents such as files and attachments that are associated with an email. Each ID is linked to a ContentDocumentLink record, which represents the relationship between an email message and a content document record.

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

Division
Type
picklist
Properties
Defaulted on create, Filter, Group, Restricted picklist, Sort
Description
A logical segment of your organization's data. For example, if your company is organized into different business units, you could create a division for each business unit, such as “North America,” “Healthcare,” or “Consulting.” Available only if the organization has the Division permission enabled.
EmailRoutingAddressId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
Stores the ID of the email routing address used to create the email. This value is set when the email is processed by Email-to-Case service. When this field is set, EmailMessage.Incoming cannot be false.
Relationship Name
EmailRoutingAddress
Relationship Type
Lookup
Refers To
EmailRoutingAddress
EmailTemplateId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The email template, if any, that was chosen for the email. This field is populated in Lightning Experience only.
This is a relationship field.
Relationship Name
EmailTemplate
Relationship Type
Lookup
Refers To
EmailTemplate
FirstOpenedDate
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
The date the email was first opened.

To see this field, enable email tracking in your org.

FromAddress
Type
email
Properties
Create, Filter, Nillable, Sort, Update
Description
The address that originated the email. When using this field, specify an email address that exists in EmailMessageRelation, with a RelationType of FromAddress.
EmailMessages in Draft status with IsPrivateDraft set to true must use the user's address, a verified org-wide email address, or a verified Email-to-Case routing address in the FromAddress field.
FromId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
Description
The contact, lead, or user who sent the email. Maximum length is 18 characters.
FromName
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
The sender’s name. When using this field, specify an email address that exists in EmailMessageRelation, with a RelationType of FromAddress.
HasAttachment
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the email was sent with an attachment (true) or not (false).
Headers
Type
textarea
Properties
Create, Nillable, Update
Description
The Internet message headers of the incoming email. Used for debugging and tracing purposes. Doesn’t apply to outgoing emails.
HtmlBody
Type
textarea
Properties
Create, Nillable, Update
Description
The body of the email in HTML format.
You can’t send emails unless at least one of these fields has content.
  • Subject field
  • HTML Body or Text Body field
As the sender, you can provide the content, or it can be automatically inserted using predefined values. An email template can also include the content for these fields.
Incoming
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort
Description
Indicates whether the email was received (true) or sent (false).
IsBounced
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Indicates whether the email bounced.

This field is set to True for bounced emails in orgs using Lightning Threading. It’s not set to True for orgs using Ref ID threading.

To see this field, enable bounce management in your org.

IsClientManaged
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort
Description
If EmailMessage is created with IsClientManaged set to true, users can modify EmailMessage.ContentDocumentIds to link file attachments even when the Status of the EmailMessage isn’t set to Draft. When this field is set to true and Enhanced Email is enabled, a Task record is created for the EmailMessage regardless of Email-to-Case settings.
IsDeleted
Type
boolean
Properties
Defaulted on create, Filter
Description
Indicates whether the object has been moved to the Recycle Bin (true) or not (false). Label is Deleted.
IsExternallyVisible
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
If the Experience Cloud site case feed is enabled, IsExternallyVisible controls the external visibility of emails in sites. When IsExternallyVisible is set to true—its default value—external users see the email message in the case feed.
  • Emails remain visible in the Emails related list whether or not this field is set to true. For security reasons, we recommend that you remove this related list from your case page layout for external community users.
  • Only emails with a value in the ParentId field can be made externally visible in sites.
  • This field can’t be updated if the email’s Status is set to Draft.
  • The Enable Case Feeds in Experience Cloud Sites organization preference in Setup makes case-related emails, comments, and updates visible to site members.

    When this preference is off, IsExternallyVisible is True by default for the EmailMessage. When this preference is on, IsExternallyVisible defaults to True only if the case contact email is the sender or the recipient of the EmailMessage. Otherwise, IsExternallyVisible defaults to False.
IsOpened
Type
boolean
Properties
Defaulted on create, Filter, Group, Sort
Description
Indicates whether the email has been opened.

To see this field, enable email tracking in your org.

IsPrivateDraft
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort
Description
If IsPrivateDraft is set to true, then only the CreatedById user can view, update, and send this email draft. If IsPrivateDraft is set to false, then any user with permissions to work on the case can see these drafts. After the email is sent, then this field is updated to be false. Public drafts are loaded and visible in Salesforce Classic while Private Drafts are only used in Lightning Experience.
IsTracked
Type
boolean
Properties
Create, Defaulted on create, Filter, Group, Sort, Update
Description
Indicates whether the email is being tracked.

To see this field, enable email tracking in your org.

LastOpenedDate
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
The date the email was last opened.

To see this field, enable email tracking in your org.

MessageDate
Type
dateTime
Properties
Create, Filter, Nillable, Sort, Update
Description
The date the email was created.
For inbound emails, Email-to-Case sets this field using the Date header. The Date header is set by the email client and is subject to the sender's time preferences.
MessageIdentifier
Type
string
Properties
Create, Filter, Group, idLookup, Nillable, Sort, Update
Description
The ID of the email message.
Name
Type
string
Properties
Filter, Group, idLookup, Sort
Description
A name for the email message that's derived from the first 255 characters of the Subject field. If the Subject field is empty, a localized string of [No Subject] is used. This field is read-only and can’t be created or updated. Available in API versions 56.0 and later.
ParentId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
Description
ID of the case that’s associated with the email.
This is a relationship field.
Relationship Name
Parent
Relationship Type
Lookup
Refers To
Case
RelatedToId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort, Update
Description

The RelatedToId represents nonhuman objects such as accounts, opportunities, campaigns, cases, or custom objects. RelatedToIds are polymorphic. Polymorphic means a RelatedToId is equivalent to the ID of a related object.

You must have access to at least one entity listed under Refers To to access RelatedToId.

You can update RelatedToId when IsClientManaged is set to true.

RelatedtoId and ParentId should have the same value when ParentId is set. You might see unexpected results otherwise.

This is a polymorphic relationship field.
Relationship Name
RelatedTo
Relationship Type
Lookup
Refers To
Account, Accreditation, AssessmentIndicatorDefinition, AssessmentTask, AssessmentTaskContentDocument, AssessmentTaskDefinition, AssessmentTaskOrder, Asset, AssetRelationship, AssignedResource, Award, BoardCertification, BusinessLicense, BusinessMilestone, BusinessProfile, Campaign, CareBarrier, CareBarrierDeterminant, CareBarrierType, CareDeterminant, CareDeterminantType, CareDiagnosis, CareInterventionType, CareMetricTarget, CareObservation, CareObservationComponent, CarePgmProvHealthcareProvider, CarePreauth, CarePreauthItem, CareProgram, CareProgramCampaign, CareProgramEligibilityRule, CareProgramEnrollee, CareProgramEnrolleeProduct, CareProgramEnrollmentCard, CareProgramGoal, CareProgramProduct, CareProgramProvider, CareProgramTeamMember, CareProviderAdverseAction, CareProviderFacilitySpecialty, CareProviderSearchableField, CareRegisteredDevice, CareRequest, CareRequestDrug, CareRequestExtension, CareRequestItem, CareSpecialty, CareSpecialtyTaxonomy, CareTaxonomy, Case, CommSubscriptionConsent, ContactEncounter, ContactEncounterParticipant, ContactRequest, Contract, CoverageBenefit, CoverageBenefitItem, CreditMemo, DelegatedAccount, DocumentChecklistItem, EnrollmentEligibilityCriteria, HealthcareFacility, HealthcareFacilityNetwork, HealthcarePayerNetwork, HealthcarePractitionerFacility, HealthcareProvider, HealthcareProviderNpi, HealthcareProviderSpecialty, HealthcareProviderTaxonomy, IdentityDocument, Image, IndividualApplication, Invoice, ListEmail, Location, MemberPlan, Opportunity, Order, OtherComponentTask, PartyConsent, PersonLifeEvent, PlanBenefit, PlanBenefitItem, ProcessException, Product2, ProductItem, ProductRequest, ProductRequestLineItem, ProductTransfer, PurchaserPlan, ReceivedDocument, ResourceAbsence, ReturnOrder, ReturnOrderLineItem, ServiceAppointment, ServiceResource, Shift, Shipment, ShipmentItem, Solution, Visit, VisitedParty, VolunteerProject, WorkOrder, WorkOrderLineItem
ReplyToEmailMessageId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
Description
ID of the inbound or outbound email message the current email message is a reply to. It’s not possible to reply to a message whose Status is Draft.
This is a relationship field.
This is only set for Case related Email replies at setup.
Relationship Name
ReplyToEmailMessage
Relationship Type
Lookup
Refers To
EmailMessage
Source
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort
Description
When Sync Email as Salesforce Activity is enabled, this value reflects from where the email was captured automatically.
Possible values are:
  • Einstein Activity Capture–Captured as an entire email message by Einstein Activity Capture.
  • Einstein Activity Capture Limited–Captured as a header-only email by Einstein Activity Capture. The sender, recipients, date, and time of the message were captured, not the subject or body.
  • Email Integration App Manual-Captured to track the email message records created or edited from the mailapp.
Available in API version 64.0 and later.
Status
Type
picklist
Properties
Create, Filter, Group, Restricted picklist, Sort, Update
Description
The status of the email.

The Status field is mostly read-only. You can change the status only from New to Read.

Possible values are:
  • 0 (New)
  • 1 (Read)
  • 2 (Replied)
  • 3 (Sent)
  • 4 (Forwarded)
  • 5 (Draft)
For emails not sent as part of a case, only the status 3 (Sent) is valid.
Subject
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
The subject line of the email.
You can’t send emails unless at least one of these fields has content.
  • Subject field
  • HTML Body or Text Body field
As the sender, you can provide the content, or it can be automatically inserted using predefined values. An email template can also include the content for these fields.
TextBody
Type
textarea
Properties
Create, Nillable, Update
Description
The body of the email, in plain text format. If TextBody isn’t set, then it’s extracted from HtmlBody.
You can’t send emails unless at least one of these fields has content.
  • Subject field
  • HTML Body or Text Body field
As the sender, you can provide the content, or it can be automatically inserted using predefined values. An email template can also include the content for these fields
ThreadIdentifier
Type
string
Properties
Create, Filter, Group, idLookup, Nillable, Sort, Update
Description
The ID of the email thread the email message belongs to. This field is used by features that sync emails directly from an inbox into Salesforce. This field is not used by On-Demand Email-to-Case.
ToAddress
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
A string array of email addresses for recipients who were sent the email message. Include only email addresses that aren’t associated with Contact, Lead, or User records in Salesforce. If the recipient is a contact, lead, or user, add their ID to the ToIds field instead of adding their email address to the ToAddress field. Then the email message is automatically associated with the contact, lead, or user.
You can’t send emails unless there’s at least one recipient.
ToIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for contacts, leads, and users who were sent a carbon copy of the email message. Each ID is linked to an EmailMessageRelation record, which represents the relationship between an email message and a Contact, Lead, or User record.

Adding a JunctionIdList field name to the fieldsToNull property deletes all related junction records. This action can’t be undone.

ValidatedFromAddress
Type
picklist
Properties
Create, Filter, Group, Nillable, Restricted picklist, Sort, Update
Description

A picklist value with either the sender's address, org-wide email addresses, or Email-to-Case routing address. The email address must be verified. If the sender’s email address is used, the sender must be the current user.

ValidatedFromAddress isn’t suitable for use in Group By or Sort By statements. Use FromAddress instead.

Usage

EmailMessage is limited to 50 custom fields.

If your org uses Email-to-Case, a case is created when an email is sent to one of your company’s addresses. The email, which is related to the case by the ParentID field, is stored as an EmailMessage record. When users view the email, they see the EmailMessage record.

If your org uses Enhanced Email, each email is stored as an EmailMessage record and a Task record. When users view an email, they see the EmailMessage record.

In an org with Email-to-Case enabled, an inbound (Incoming = true) email with case as the parent record won’t create a task automatically. This functionality respects the Create Task from Email setting for each Email-to-Case routing address.

Note

If you would like to change the recipients or contents of an outbound email, don’t use automation tools, like Flows or Apex triggers, to update EmailMessage records. Unless they are for a draft, updates to EmailMessage records will not be reflected in the actual sent email. To update an email’s data before it’s sent, use Quick Action predefined values or a QuickActionDefaultsHandler.

When a Flow creates an EmailMessage with set values in the audit fields (like CreatedBy and CreatedDate), any FeedItem automatically created for that EmailMessage will not share the same audit field values.

Sample Code—Apex

This sample logs email activity in Salesforce.

// if EnhancedEmail Perm is not enabled, continue logging the email as a task

// if EnhancedEmail Perm is enabled, create an EmailMessage object
EmailMessage emailMessage = new EmailMessage();
emailMessage.status = '3'; // email was sent
emailMessage.relatedToId = '006B0000003weZGIAY'; // related to record e.g. an opportunity
emailMessage.fromAddress = 'sender@example.com'; // from address
emailMessage.fromName = 'Dan Perkins'; // from name
emailMessage.subject = 'This is the Subject!'; // email subject
emailMessage.htmlBody = '<html><body><b>Hello</b></body></html>'; // email body
// Contact, Lead or User Ids of recipients
String[] toIds = new String[]{'003B000000AxcEjIAJ'}; 
emailMessage.toIds = toIds;
// additional recipients who don’t have a corresponding contact, lead or user id in the Salesforce org (optional)
emailMessage.toAddress = 'emailnotinsalesforce@toexample.com, anotherone@toexample.com';
insert emailMessage; // insert

// Add Email Message Relation for id of the sender
EmailMessageRelation emr = new EmailMessageRelation();
emr.emailMessageId = emailMessage.id;
emr.relationId = '005B0000003qHvOIAU'; // user id of the sender
emr.relationType = 'FromAddress';
insert emr;

Associated Objects

This object has the following associated objects. If the API version isn’t specified, they’re available in the same API versions as this object. Otherwise, they’re available in the specified API version and later.

EmailMessageChangeEvent (API version 48.0)
Change events are available for the object.