EmailMessage

Represents an email in Salesforce.

Supported Calls

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

Special Access Rules

EmailMessage is only available for organizations 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.

Customer Portal users have read access to EmailMessage if the value for the ParentID field is associated with a case. Otherwise, access is determined by sharing access of the associated task.

update() is supported only on records whose Status is Draft, and IsPrivateDraft is false. Or, if Status and IsPrivateDraft is true and CreatedBy is associated with the current use. When a record’s is not Draft, update() is supported only for the IsExternallyVisible field and custom fields.. When a record’s Status is not Draft, update() is supported only for the IsExternallyVisible field and custom fields.

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.
BccAddress
Type
string
Properties
Create, Filter, Nillable, Sort, Update
Description
A string array of email addresses for recipients who were sent a blind carbon copy of the email message. Include only email addresses that are not 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. Then the email message is automatically associated with the contact, lead, or user.
BccIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for contacts, leads, and users who were sent a blind 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.
Warning

Warning

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 are not 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.
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.
Warning

Warning

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

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.
Warning

Warning

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

FromAddress
Type
email
Properties
Create, Filter, Nillable, 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.
FromName
Type
string
Properties
Create, Filter, Nillable, 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
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. Does not apply to outgoing emails.
HtmlBody
Type
textarea
Properties
Create, Nillable, Update
Description
The body of the email in HTML format.
Incoming
Type
boolean
Properties
Create, Defaulted on create, Filter
Description
Indicates whether the email was received (true) or sent (false).
IsClientManaged
Type
boolean
Properties
Create, Defaulted on create, Filter, Group
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 is not set to Draft.
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
Create, Defaulted on create, Filter, Group, Update
Description
If the community case feed is enabled, IsExternallyVisible controls the external visibility of emails in communities. When IsExternallyVisible is set to true—its default value—email messages are visible to external users in the case feed.
Only emails with the ParentId field populated are available to be externally visible in communities.
This field can’t be updated if the email’s Status is set to Draft.
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. Once the email is sent (Email Status = Draft), 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.
MessageDate
Type
dateTime
Properties
Create, Filter, Nillable, Update
Description
The date the email was created.
MessageIdentifier
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The ID of the email message.
ParentId
Type
ID
Properties
Create, Filter, Group, Nillable, Sort
Description
ID of the case that’s associated with the email.
RelatedToId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
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.

ReplyToEmailMessageId
Type
reference
Properties
Create, Filter, Group, Nillable, Sort
Description
ID of the inbound or outbound EmailMessage the current EmailMessage is a reply to. It’s not possible to reply to a message whose Status is Draft.
Status
Type
picklist
Properties
Create, Filter, Restricted picklist, Update
Description
Read only. The status of the email. For example, New, Read, Replied, Sent, Forwarded, or Draft.
Subject
Type
string
Properties
Create, Filter, Nillable, Update
Description
The subject line of the email.
ThreadIdentifier
Type
string
Properties
Create, Filter, Group, Nillable, Sort, Update
Description
The ID of the email thread the email message belongs to.
TextBody
Type
textarea
Properties
Create, Nillable, Update
Description
The body of the email, in plain text format. If TextBody is not set, then it is extracted from HtmlBody.
ToAddress
Type
string
Properties
Create, Filter, Nillable, Update
Description
A string array of email addresses for recipients who were sent the email message. Include only email addresses that are not 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.
ToIds
Type
JunctionIdList
Properties
Create, Update
Description
A string array of IDs for contacts, leads, and users who were sent 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.
Warning

Warning

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, validated org-wide email addresses that originated the email, or Email-to-Case Routing Address.

Usage

If your organization 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 organization 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.

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;

See Also