sendEmail()

Syntax

For single email messages:

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

For mass email messages:

1SendEmailResult = 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 SingleEmailMessage.targetObjectId or MassEmailMessage.targetObjectIds is set, bounces are processed by Salesforce automatically, and the appropriate records are updated; otherwise, they go to the logged-in user. Bounce management works for contacts and leads only.

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.

1public void doSendEmail() {
2   try {
3      EmailFileAttachment efa = new EmailFileAttachment();
4      byte[] fileBody = new byte[1000000];
5      efa.setBody(fileBody);
6      efa.setFileName("attachment");
7      SingleEmailMessage message = new SingleEmailMessage();
8      message.setBccAddresses(new String[] {
9         "someone@salesforce.com"
10      });
11      message.setCcAddresses(new String[] {
12         "person1@salesforce.com", "person2@salesforce.com", "003xx00000a1b2cAAC"
13      });
14      message.setBccSender(true);
15      message.setEmailPriority(EmailPriority.High);
16      message.setReplyTo("person1@salesforce.com");
17      message.setSaveAsActivity(false);
18      message.setSubject("This is how you use the " + "sendEmail method.");
19      // We can also just use an id for an implicit to address
20      GetUserInfoResult guir = connection.getUserInfo();
21      message.setTargetObjectId(guir.getUserId());
22      message.setUseSignature(true);
23      message.setPlainTextBody("This is the humongous body "
24            + "of the message.");
25      EmailFileAttachment[] efas = { efa };
26      message.setFileAttachments(efas);
27      message.setToAddresses(new String[] { "person3@salesforce.com" });
28      SingleEmailMessage[] messages = { message };
29      SendEmailResult[] results = connection.sendEmail(messages);
30      if (results[0].isSuccess()) {
31         System.out.println("The email was sent successfully.");
32      } else {
33         System.out.println("The email failed to send: "
34               + results[0].getErrors()[0].getMessage());
35      }
36   } catch (ConnectionException ce) {
37      ce.printStackTrace();
38   }
39}

This example shows how to send an email with the opt-out setting enforced. Recipients are specified by their IDs. The SendEmailOptOutPolicy.FILTER option causes the email to be sent only to recipients that haven’t opted out from email.

1SingleEmailMessage message = new SingleEmailMessage();
2// Set recipients to two contact IDs.
3// Replace IDs with valid record IDs in your org.
4message.setToAddresses(new String[] { "003D000000QDexS", "003D000000QDfW5" });
5message.setOptOutPolicy(SendEmailOptOutPolicy.FILTER);
6message.setSubject("Opt Out Test Message");
7message.setPlainTextBody("This is the message body.");
8SingleEmailMessage[] messages = { message };
9SendEmailResult[] results = connection.sendEmail(messages);
10if (results[0].isSuccess()) {
11    System.out.println("The email was sent successfully.");
12} else {
13    System.out.println("The email failed to send: "
14          + results[0].getErrors()[0].getMessage());
15}

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.

1public void doSendEmail()
2{
3   try
4   {
5      EmailFileAttachment efa = new EmailFileAttachment();
6      byte[] fileBody = new byte[1000000];
7      efa.body = fileBody;
8      efa.fileName = "attachment";
9      SingleEmailMessage message = new SingleEmailMessage();
10      message.setBccAddresses(new String[] {
11         "someone@salesforce.com"
12      });
13      message.setCcAddresses(new String[] {
14         "person1@salesforce.com", "person2@salesforce.com", "003xx00000a1b2cAAC"
15      });
16      message.bccSender = true;
17      message.emailPriority = EmailPriority.High;
18      message.replyTo = "person1@salesforce.com";
19      message.saveAsActivity = false;
20      message.subject = "This is how you use the " + "sendEmail method.";
21      // We can also just use an id for an implicit to address
22      GetUserInfoResult guir = binding.getUserInfo();
23      message.targetObjectId = guir.userId;
24      message.useSignature = true;
25      message.plainTextBody = "This is the humongous body "
26            + "of the message.";
27      EmailFileAttachment[] efas = { efa };
28      message.fileAttachments = efas;
29      message.toAddresses = new String[] { "person3@salesforce.com" };
30      SingleEmailMessage[] messages = { message };
31      SendEmailResult[] results = binding.sendEmail(messages);
32      if (results[0].success)
33      {
34         Console.WriteLine("The email was sent successfully.");
35      }
36      else
37      {
38         Console.WriteLine("The email failed to send: "
39               + results[0].errors[0].message);
40      }
41   }
42   catch (SoapException e)
43   {
44      Console.WriteLine("An unexpected error has occurred: " +
45                        e.Message + "\n" + e.StackTrace);
46   }
47}

This example shows how to send an email with the opt-out setting enforced. Recipients are specified by their IDs. The SendEmailOptOutPolicy.FILTER option causes the email to be sent only to recipients that haven’t opted out from email.

1SingleEmailMessage message = new 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 = SendEmailOptOutPolicy.FILTER;
6message.subject = "Opt Out Test Message";
7message.plainTextBody = "This is the message body.";
8SingleEmailMessage[] messages = { message };
9SendEmailResult[] results = binding.sendEmail(messages);
10if (results[0].success) 
11{
12    Console.WriteLine("The email was sent successfully.");
13} else {
14    Console.WriteLine("The email failed to send: "
15          + results[0].errors[0].message);
16}

BaseEmail

SingleEmailMessage

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

MassEmailMessage

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

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.

Response

SendEmailResult

Fault

The following API status codes can be returned. Also, sendEmail() can return other errors when rendering email templates. See renderEmailTemplate() Faults.

BCC_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

BCC_SELF_NOT_ALLOWED_IF_BCC_COMPLIANCE_ENABLED

DUPLICATE_SENDER_DISPLAY_NAME

EMAIL_ADDRESS_BOUNCED

EMAIL_NOT_PROCESSED_DUE_TO_PRIOR_ERROR

EMAIL_OPTED_OUT

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