sendEmail()

Syntax

For single email messages:

SendEmailResult = sfdc.sendEmail( BaseEmail  SingleEmailMessage emails[]);

For mass email messages:

SendEmailResult = sfdc.sendEmail( BaseEmail  MassEmailMessage emails[]);

Usage

Use this call with Force.comAppExchange 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 user calling this API is inserted in the From Address field of the email header. All return email and out-of-office replies go to the user calling the API. If bounce management is enabled, bounces will be processed by Salesforce automatically, and the appropriate record is updated; otherwise, they go to the user calling the API.

Note

All mass email and single email messages sent with this call count against the daily mass mail limit of the sending organization. When the daily mass mail limit for the organization is reached, all sendEmail calls through the API are rejected, and the user receives a MASS_MAIL_LIMIT_EXCEEDED error code. However, single email messages sent through the application are still allowed.

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.

Sample Code—Java

private void sendEmailSample() {
   // Verify that we are already authenticated,
   // if not call the login function to do so 
   if (!loggedIn) {
      if (!login()) { 
         return;
      } 
   }
   byte[] fileBody = new byte[1000000];
   EmailFileAttachment[] fileAttachments = new EmailFileAttachment[1];
   EmailFileAttachment fileAttachment = new EmailFileAttachment();
   fileAttachment.setBody(fileBody);
   fileAttachment.setFileName(“attachment”);
   fileAttachments[0] = fileAttachment;
   SingleEmailMessage[] messages = new SingleEmailMessage[1];
   messages[0] = new SingleEmailMessage();  
   messages[0].setBccAddresses(new String[] {"jdoe@acme.com", "jdoe@merce.com" });
   messages[0].setCcAddresses(new String[] {"jdoe@gmail.com", "jdoe@salesforce.com" } );
   messages[0].setBccSender(true);
   messages[0].setEmailPriority(EmailPriority.High);
   messages[0].setReplyTo("dcarroll@salesforce.com");
   messages[0].setSaveAsActivity(true);
   messages[0].setSubject("This is how you use the sendEmail call.");
   //We can also just use an id for an implicit to address
   messages[0].setTargetObjectId("003D0000005OV0g");
   messages[0].setUseSignature(true);
   messages[0].setPlainTextBody("This is the humongous body of the message.");
   messages[0].setFileAttachments(fileAttachments);
   String[] toAddresses = new String[] {  "jdoe@salesforce.com" };
   messages[0].setToAddresses(toAddresses);
   //binding.
   try { 
      SendEmailResult[] result = binding.sendEmail(messages);
      if (result[i].isSuccess()){
         System.out.println("The email was send successfully.");
      }
      else{
         System.out.println("The email failed to send: " + result[i].getErrors(0).getMessage());
      }
   }
   getUserInput("\nPress return to continue.");
   }
      catch (UnexpectedErrorFault e) {
         // TODO Auto-generated catch block
         e.printStackTrace();
      }
      catch (RemoteException e) { 
      // TODO Auto-generated catch block
      e.printStackTrace();
   }
}

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

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 five. This argument is allowed only when a template is not used. 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. 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 five. 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.
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.
plainTextBody	string	Optional. The text version of the email, specified by the sender.
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 ten. 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.

EmailFileAttachment

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

Response

SendEmailResult

Fault

BCC_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

BCC_SELF_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

EMAIL_NOT_PROCESSED_DUE_TO_PRIOR_ERROR

ERROR_IN_MAILER

INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY

INVALID_EMAIL_ADDRESS

INVALID_ID_FIELD

INVALID_SAVE_AS_ACTIVITY_FLAG

LIMIT_EXCEEDED

MALFORMED_ID

MASS_MAIL_LIMIT_EXCEEDED

NO_MASS_MAIL_PERMISSION

REQUIRED_FIELD_MISSING

TEMPLATE_NOT_ACTIVE