Newer Version Available

This content describes an older version of this product. View Latest

SingleEmailMessage Methods

Contains methods for sending single email messages.

Namespace

Usage

SingleEmailMessage extends Email and inherits all of its methods. All base email (Email class) methods are also available to the SingleEmailMessage objects.

Email properties are readable and writable. Each property has corresponding setter and getter methods. For example, the toAddresses() property is equivalent to the setToAddresses() and getToAddresses() methods. Only the setter methods are documented. However, the getTemplateName() method doesn’t have an equivalent setter method; use setTemplateId() to specify a template name.

SingleEmailMessage Constructors

The following are constructors for SingleEmailMessage.

SingleEmailMessage()

Creates a new instance of the Messaging.SingleEmailMessage class.

Signature

public SingleEmailMessage()

SingleEmailMessage Methods

The following are methods for SingleEmailMessage. All are instance methods. All base email (Email class) methods are also available to the SingleEmailMessage objects. These methods are described in Email Class (Base Email Methods).

getTemplateName()

The name of the template used to create the email.

Signature

public STRING getTemplateName()

Return Value

Type: String

Usage

There is no equivalent setter method for getTemplateName(). If the email didn’t use a template, getTemplateName() returns nothing. If you use setTemplateId(), and then call getTemplateName(), the template name associated to the template ID is returned.

setBccAddresses(bccAddresses)

Optional. A list of blind carbon copy (BCC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum allowed is 25.

Signature

public Void setBccAddresses(String[] bccAddresses)

Parameters

bccAddresses: Type: String[]

Return Value

Type: Void

Usage

All emails must have a recipient value in at least one of the following fields:

toAddresses
ccAddresses
bccAddresses
targetObjectId

If the BCC compliance option is set at the organization level, the user cannot add BCC addresses on standard messages. The following error code is returned: BCC_NOT_ALLOWED_IF_BCC_ COMPLIANCE_ENABLED. Contact your Salesforce representative for information on BCC compliance.

setCcAddresses(ccAddresses)

Optional. A list of carbon copy (CC) addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum allowed is 25.

Signature

public Void setCcAddresses(String[] ccAddresses)

Parameters

ccAddresses: Type: String[]

Return Value

Type: Void

Usage

All emails must have a recipient value in at least one of the following fields:

toAddresses
ccAddresses
bccAddresses
targetObjectId

setCharset(characterSet)

Optional. The character set for the email. If this value is null, the user's default value is used.

Signature

public Void setCharset(String characterSet)

Parameters

characterSet: Type: String

Return Value

Type: Void

setDocumentAttachments(documentIds)

(Deprecated. Use setEntityAttachments() instead.) Optional. A list containing the ID of each document object you want to attach to the email.

Signature

public Void setDocumentAttachments(ID[] documentIds)

Parameters

documentIds: Type: ID[]

Return Value

Type: Void

Usage

You can attach multiple documents as long as the total size of all attachments does not exceed 10 MB.

setEntityAttachments(ids)

Optional. Array of IDs of Document, ContentVersion, or Attachment items to attach to the email.

Signature

public void setEntityAttachments(List<String> ids)

Parameters

ids: Type: List<String>

Return Value

Type: void

setFileAttachments(fileNames)

Optional. A list containing the file names of the binary and text files you want to attach to the email.

Signature

public Void setFileAttachments(EmailFileAttachment[] fileNames)

Parameters

fileNames: Type: Messaging.EmailFileAttachment[]

Return Value

Type: Void

Usage

You can attach multiple files as long as the total size of all attachments does not exceed 10 MB.

setHtmlBody(htmlBody)

Optional. The HTML version of the email, specified by the sender. The value is encoded according to the specification associated with the organization. You must specify a value for setTemplateId, setHtmlBody, or setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.

Signature

public Void setHtmlBody(String htmlBody)

Parameters

htmlBody: Type: String

Return Value

Type: Void

setInReplyTo(parentMessageIds)

Sets the optional In-Reply-To field of the outgoing email. This field identifies the email or emails to which this email is a reply (parent emails).

Signature

public Void setInReplyTo(String parentMessageIds)

Parameters

parentMessageIds: Type: String; Contains one or more parent email message IDs.

Return Value

Type: Void

setOptOutPolicy(emailOptOutPolicy)

Optional. If you added recipients by ID instead of email address and the Email Opt Out option is set, this method determines the behavior of the sendEmail() call. If you add recipients by their email addresses, the opt-out settings for those recipients aren’t checked and those recipients always receive the email.

Signature

public void setOptOutPolicy(String emailOptOutPolicy)

Parameters

emailOptOutPolicy

Type: String

Possible values of the emailOptOutPolicy parameter are:

SEND (default)—The email is sent to all recipients and the Email Opt Out option of the recipients is ignored.
FILTER—No email is sent to the recipients that have the Email Opt Out option set and emails are sent to the other recipients.
REJECT—If any of the recipients have the Email Opt Out option set, sendEmail() throws an error and no email is sent.

Return Value

Type: void

Example

This example shows how to send an email with the opt-out setting enforced. Recipients are specified by their IDs. The FILTER option causes the email to be sent only to recipients that haven’t opted out from email. This example uses dot notation of the email properties, which is equivalent to using the set methods.

1Messaging.SingleEmailMessage message = new Messaging.SingleEmailMessage();
2// Set recipients to two contact IDs.
3// Replace IDs with valid record IDs in your org.
4message.toAddresses = new String[] { '003D000000QDexS', '003D000000QDfW5' };
5message.optOutPolicy = 'FILTER';
6message.subject = 'Opt Out Test Message';
7message.plainTextBody = 'This is the message body.';
8Messaging.SingleEmailMessage[] messages = 
9    new List<Messaging.SingleEmailMessage> {message};
10         Messaging.SendEmailResult[] results = Messaging.sendEmail(messages);
11if (results[0].success) {
12    System.debug('The email was sent successfully.');
13} else {
14    System.debug('The email failed to send: '
15          + results[0].errors[0].message);
16}

setPlainTextBody(plainTextBody)

Optional. The text version of the email, specified by the sender. You must specify a value for setTemplateId, setHtmlBody, or setPlainTextBody. Or, you can define both setHtmlBody and setPlainTextBody.

Signature

public Void setPlainTextBody(String plainTextBody)

Parameters

plainTextBody: Type: String

Return Value

Type: Void

setOrgWideEmailAddressId(emailAddressId)

Optional. The ID of the organization-wide email address associated with the outgoing email. The object's DisplayName field cannot be set if the setSenderDisplayName field is already set.

Signature

public Void setOrgWideEmailAddressId(ID emailAddressId)

Parameters

emailAddressId: Type: ID

Return Value

Type: Void

setReferences(references)

Optional. The References field of the outgoing email. Identifies an email thread. Contains the parent emails' References and message IDs, and possibly the In-Reply-To fields.

Signature

public Void setReferences(String references)

Parameters

references: Type: String

Return Value

Type: Void

setSubject(subject)

Optional. The email subject line. If you are using an email template, the subject line of the template overrides this value.

Signature

public Void setSubject(String subject)

Parameters

subject: Type: String

Return Value

Type: Void

setTargetObjectId(targetObjectId)

Required if using a template, optional otherwise. The ID of the contact, lead, or user to which the email will be sent. The ID you specify sets the context and ensures that merge fields in the template contain the correct data.

Signature

public Void setTargetObjectId(ID targetObjectId)

Parameters

targetObjectId: Type: ID

Return Value

Type: Void

Usage

Do not specify the IDs of records that have the Email Opt Out option selected.

All emails must have a recipient value in at least one of the following fields:

toAddresses
ccAddresses
bccAddresses
targetObjectId

setTemplateId(templateId)

Required if using a template, optional otherwise. The ID of the template used to create the email.

Signature

public Void setTemplateId(ID templateId)

Parameters

templateId: Type: ID

Return Value

Type: Void

setToAddresses(toAddresses)

Optional. A list of email addresses or object IDs of the contacts, leads, and users you’re sending the email to. The maximum number of email addresses allowed is 100.

Signature

public Void setToAddresses(String[] toAddresses)

Parameters

toAddresses: Type: String[]

Return Value

Type: Void

Usage

All emails must have a recipient value in at least one of the following fields:

toAddresses
ccAddresses
bccAddresses
targetObjectId

setTreatBodiesAsTemplate(treatAsTemplate)

Optional. If set to true, the subject, plain text, and HTML text bodies of the email are treated as template data.

Signature

public void setTreatBodiesAsTemplate(Boolean treatAsTemplate)

Parameters

treatAsTemplate: Type: Boolean

Return Value

Type: void

setTreatTargetObjectAsRecipient(treatAsRecipient)

Optional. If set to true, the targetObjectId (a contact, lead, or user) is the recipient of the email. If set to false, the targetObjectId is supplied as the WhoId field for template rendering but isn’t a recipient of the email. The default is true.

Signature

public void setTreatTargetObjectAsRecipient(Boolean treatAsRecipient)

Parameters

treatAsRecipient: Type: Boolean

Return Value

Type: void

Usage

You can set TO, CC, and BCC addresses using the email messaging methods regardless of whether a template is used for the email or the target object is a recipient.

Note

setWhatId(whatId)

If you specify a contact for the targetObjectId field, you can specify an optional whatId as well. This helps to further ensure that merge fields in the template contain the correct data.

Signature

public Void setWhatId(ID whatId)

Parameters

whatId: Type: ID

Return Value

Type: Void

Usage

The value must be one of the following types:

Account
Asset
Campaign
Case
Contract
Opportunity
Order
Product
Solution
Custom

Apex Developer Guide

SingleEmailMessage Methods

Namespace

Usage

See Also

SingleEmailMessage Constructors

SingleEmailMessage()

Signature

SingleEmailMessage Methods

getTemplateName()

Signature

Return Value

Usage

setBccAddresses(bccAddresses)

Signature

Parameters

Return Value

Usage

setCcAddresses(ccAddresses)

Signature

Parameters

Return Value

Usage

setCharset(characterSet)

Signature

Parameters

Return Value

setDocumentAttachments(documentIds)

Signature

Parameters

Return Value

Usage

setEntityAttachments(ids)

Signature

Parameters

Return Value

setFileAttachments(fileNames)

Signature

Parameters

Return Value

Usage

setHtmlBody(htmlBody)

Signature

Parameters

Return Value

setInReplyTo(parentMessageIds)

Signature

Parameters

Return Value

setOptOutPolicy(emailOptOutPolicy)

Signature

Parameters

Return Value

Example

setPlainTextBody(plainTextBody)

Signature

Parameters

Return Value

setOrgWideEmailAddressId(emailAddressId)

Signature

Parameters

Return Value

setReferences(references)

Signature

Parameters

Return Value

setSubject(subject)

Signature

Parameters

Return Value

setTargetObjectId(targetObjectId)

Signature

Parameters

Return Value

Usage

setTemplateId(templateId)

Signature

Parameters

Return Value

setToAddresses(toAddresses)