sendEmail()

Immediately sends an email message.

Syntax

For single email messages:

SendEmailResult = connection.sendEmail(SingleEmailMessage emails[]);

For mass email messages:

SendEmailResult = connection.sendEmail(MassEmailMessage emails[]);

Usage

Use this call with Force.com AppExchange applications, custom applications, or other applications outside of Salesforce to send individual and mass email. The email can include all standard email attributes (such as subject line and blind carbon copy address), use Salesforce email templates, and be in plain text or HTML format. You can use Salesforce to track the status of HTML email, including the date the email was sent, first opened, last opened, and the total number of times it was opened. (See “Tracking HTML Email” in the Salesforce online help for more information.)

The email address of the logged-in user is inserted in the From Address field of the email header. All return email and out-of-office replies go to the logged-in user. If bounce management is enabled and targetObjectId or targetObjectIds is set, bounces are processed by Salesforce automatically, and the appropriate records are updated; otherwise, they go to the logged-in user.

Note
  • Single email messages sent with this call count against the sending organization's daily single email limit. When this limit is reached, sendEmail() calls using SingleEmailMessage are rejected, and the user receives a SINGLE_EMAIL_LIMIT_EXCEEDED error code. However, single emails sent through the application are allowed.
  • Mass email messages sent with this call count against the sending organization's daily mass email limit. When this limit is reached, sendEmail() calls using MassEmailMessage are rejected, and the user receives a MASS_MAIL_LIMIT_EXCEEDED error code.
  • If you use this call to send email to one or more recipients who have the Email Opt Out option selected, the call returns UNKNOWN_EXCEPTION. In such cases, do not report the error. Instead, either remove the recipient or have the administrator deselect the option for that recipient.
SingleEmailMessage has an optional field called OrgWideEmailAddressId. This is an object ID to an OrgWideEmailAddress object. If OrgWideEmailAddressId is set, the OrgWideEmailAddress.DisplayName field is used in the email header, instead of the logged-in user's Display Name. The sending email address in the header is also set to the field defined in OrgWideEmailAddress.Address.
Note
If both the DisplayName in an OrgWideEmailAddress and senderDisplayName are defined, the user receives a DUPLICATE_SENDER_DISPLAY_NAME error.

Sample Code—Java

This sample creates an email message and sets its fields, including the To, CC and BCC recipients, subject, and body text. It also sets a recipient to the ID of the logged-in user using the setTargetObjectId method, which causes the email to be sent to the email address of the specified user. The sample creates an attachment and sends the email message with the attachment. Finally, it writes a status message or an error message, if any, to the console.

public void doSendEmail() {
   try {
      EmailFileAttachment efa = new EmailFileAttachment();
      byte[] fileBody = new byte[1000000];
      efa.setBody(fileBody);
      efa.setFileName("attachment");
      SingleEmailMessage message = new SingleEmailMessage();
      message.setBccAddresses(new String[] {
         "someone@salesforce.com"
      });
      message.setCcAddresses(new String[] {
         "person1@salesforce.com", "person2@salesforce.com"
      });
      message.setBccSender(true);
      message.setEmailPriority(EmailPriority.High);
      message.setReplyTo("person1@salesforce.com");
      message.setSaveAsActivity(false);
      message.setSubject("This is how you use the " + "sendEmail method.");
      // We can also just use an id for an implicit to address
      GetUserInfoResult guir = connection.getUserInfo();
      message.setTargetObjectId(guir.getUserId());
      message.setUseSignature(true);
      message.setPlainTextBody("This is the humongous body "
            + "of the message.");
      EmailFileAttachment[] efas = { efa };
      message.setFileAttachments(efas);
      message.setToAddresses(new String[] { "person3@salesforce.com" });
      SingleEmailMessage[] messages = { message };
      SendEmailResult[] results = connection.sendEmail(messages);
      if (results[0].isSuccess()) {
         System.out.println("The email was sent successfully.");
      } else {
         System.out.println("The email failed to send: "
               + results[0].getErrors()[0].getMessage());
      }
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

Sample Code—C#

This sample creates an email message and sets its fields, including the To, CC and BCC recipients, subject, and body text. It also sets a recipient to the ID of the logged-in user using the setTargetObjectId method, which causes the email to be sent to the email address of the specified user. The sample creates an attachment and sends the email message with the attachment. Finally, it writes a status message or an error message, if any, to the console.

public void doSendEmail()
{
   try
   {
      EmailFileAttachment efa = new EmailFileAttachment();
      byte[] fileBody = new byte[1000000];
      efa.body = fileBody;
      efa.fileName = "attachment";
      SingleEmailMessage message = new SingleEmailMessage();
      message.setBccAddresses(new String[] {
         "someone@salesforce.com"
      });
      message.setCcAddresses(new String[] {
         "person1@salesforce.com", "person2@salesforce.com"
      });
      message.bccSender = true;
      message.emailPriority = EmailPriority.High;
      message.replyTo = "person1@salesforce.com";
      message.saveAsActivity = false;
      message.subject = "This is how you use the " + "sendEmail method.";
      // We can also just use an id for an implicit to address
      GetUserInfoResult guir = binding.getUserInfo();
      message.targetObjectId = guir.userId;
      message.useSignature = true;
      message.plainTextBody = "This is the humongous body "
            + "of the message.";
      EmailFileAttachment[] efas = { efa };
      message.fileAttachments = efas;
      message.toAddresses = new String[] { "person3@salesforce.com" };
      SingleEmailMessage[] messages = { message };
      SendEmailResult[] results = binding.sendEmail(messages);
      if (results[0].success)
      {
         Console.WriteLine("The email was sent successfully.");
      }
      else
      {
         Console.WriteLine("The email failed to send: "
               + results[0].errors[0].message);
      }
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                        e.Message + "\n" + e.StackTrace);
   }
}

BaseEmail

The following table contains the arguments used in both single and mass email.
Note
If templates are not being used, all email content must be in plain text, HTML, or both.
Name Type Description
bccSender boolean Indicates whether the email sender receives a copy of the email that is sent. For a mass mail, the sender is only copied on the first email sent.
Note
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.
saveAsActivity boolean Optional. The default value is true, meaning the email is saved as an activity. This argument only applies if the recipient list is based on targetObjectId or targetObjectIds. If HTML email tracking is enabled for the organization, you will be able to track open rates.
useSignature boolean Indicates whether the email includes an email signature if the user has one configured. The default is true, meaning if the user has a signature it is included in the email unless you specify false.
emailPriority picklist Optional. The priority of the email.
  • Highest
  • High
  • Normal
  • Low
  • Lowest
The default is Normal.
replyTo string Optional. The email address that receives the message when a recipient replies. This cannot be set if you are using a Visualforce email template that specifies a replyTo value.
subject string Optional. The email subject line. If you are using an email template and attempt to override the subject line, an error message is returned.
templateId ID The ID of the template to be merged to create this email.
senderDisplayName string Optional. The name that appears on the From line of the email. This cannot be set if the object associated with a OrgWideEmailAddressId for a SingleEmailMessage has defined its DisplayName field.

SingleEmailMessage

The following table contains the arguments single email uses in addition to the base email arguments.

Name Type Description
bccAddresses string[] Optional. An array of blind carbon copy (BCC) addresses. The maximum allowed is 25. This argument is allowed only when a template is not used.

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.

All emails must have a recipient value in at least one of the following:
  • toAddresses
  • ccAddresses
  • bccAddresses
  • targetObjectId
  • targetObjectIds
ccAddresses string[] Optional. An array of carbon copy (CC) addresses. The maximum allowed is 25. This argument is allowed only when a template is not used.
charset string Optional. The character set for the email. If this value is null, the user's default value is used. Unavailable if specifying templateId because the template specifies the character set.
documentAttachments ID[] Optional. An array listing the ID of each Document you want to attach to the email. You can attach multiple documents as long as the total size of all attachments does not exceed 10 MB.
fileAttachments EmailFileAttachment[] Optional. An array listing the file names of the binary and text files you want to attach to the email. You can attach multiple files as long as the total size of all attachments does not exceed 10 MB.
htmlBody string Optional. The HTML version of the email, specified by the sender. The value is encoded according to the specification associated with the organization.
inReplyTo string Optional. The In-Reply-To field of the outgoing email. Identifies the emails to which this one is a reply (parent emails). Contains the parent emails' Message-IDs. See RFC2822 - Internet Message Format.
orgWideEmailAddressId ID Optional. The object ID of the OrgWideEmailAddress associated with the outgoing email. OrgWideEmailAddress.DisplayName cannot be set if the senderDisplayName field is already set.
plainTextBody string Optional. The text version of the email, specified by the sender.
references string Optional. The References field of the outgoing email. Identifies an email thread. Contains the parent emails' Message-ID and References fields and possibly In-Reply-To fields. See RFC2822 - Internet Message Format.
targetObjectId ID Optional. The object ID of the contact, lead, or user the email will be sent to. The object ID you enter sets the context and ensures that merge fields in the template contain the correct data

Do not enter the object 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:
  • toAddresses
  • ccAddresses
  • bccAddresses
  • targetObjectId
  • targetObjectIds
toAddresses string[] Optional. An array of email address you are sending the email to. The maximum allowed is 100. This argument is allowed only when a template is not used.
All emails must have a recipient value in at least one of the following:
  • toAddresses
  • ccAddresses
  • bccAddresses
  • targetObjectId
  • targetObjectIds
whatId ID Optional. If you specify a contact for the targetObjectId field, you can specify a whatId as well. This helps to further ensure that merge fields in the template contain the correct data. The value must be one of the following types:
  • Account
  • Asset
  • Campaign
  • Case
  • Contract
  • Opportunity
  • Order
  • Product
  • Solution
  • Custom

MassEmailMessage

The following table contains the arguments mass email uses in addition to the base email arguments.

Name Type Description
description string A value used internally to identify the object in the mass email queue.
targetObjectIds ID[] An array of object IDs of the contacts, leads, or users the email will be sent to. The object IDs you enter set the context and ensure that merge fields in the template contain the correct data. The objects must be of the same type (either all contacts, all leads, or all users). You can list up to 250 IDs per email. If you specify a value for the targetObjectIds field, optionally specify a whatId as well to set the email context to a user, contact, or lead. This ensures that merge fields in the template contain the correct data.

Do not enter the object 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:
  • toAddresses
  • ccAddresses
  • bccAddresses
  • targetObjectId
  • targetObjectIds
whatIds ID[] Optional. If you specify an array of contacts for the targetObjectIds field, you can specify an array of whatIds as well. This helps to further ensure that merge fields in the template contain the correct data. The values must be one of the following types:
  • Contract
  • Case
  • Opportunity
  • Product
If you specify whatIds, specify one for each targetObjectId; otherwise, you will receive an INVALID_ID_FIELD error.

EmailFileAttachment

The following table contains properties that the EmailFileAttachment uses in the SingleEmailMessage object to specify attachments passed in as part of the request, as opposed to a Document passed in using the documentAttachments argument.

Property Type Description
body base64 The attachment itself.
contentType string Optional. The attachment's Content-Type.
fileName string The name of the file to attach.
inline boolean Optional. Specifies a Content-Disposition of inline (true) or attachment (false). In most cases, inline content is displayed to the user when the message is opened. Attachment content requires user action to be displayed.

Response

SendEmailResult

Fault

BCC_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

BCC_SELF_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

DUPLICATE_SENDER_DISPLAY_NAME

EMAIL_NOT_PROCESSED_DUE_TO_PRIOR_ERROR

ERROR_IN_MAILER

INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY

INVALID_CONTENT_TYPE

INVALID_EMAIL_ADDRESS

INVALID_ID_FIELD

INVALID_MESSAGE_ID_REFERENCE

INVALID_SAVE_AS_ACTIVITY_FLAG

LIMIT_EXCEEDED

MALFORMED_ID

MASS_MAIL_LIMIT_EXCEEDED

NO_MASS_MAIL_PERMISSION

REQUIRED_FIELD_MISSING

SINGLE_EMAIL_LIMIT_EXCEEDED

TEMPLATE_NOT_ACTIVE

UNVERIFIED_SENDER_ADDRESS

© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.