Sends an email message through Salesforce using the user's Salesforce account. The child commands define most of the properties of the message, including the message body. As the email is sent through the user's Salesforce connection, the "From" field of the message is automatically set to the email address set in the user's Salesforce account, unless the attribute orgWideEmailAddressId is defined in which case an organization-wide alias may be used instead.

Mail & Mail2

Mail and its newer sibling command mail2 differ only in how they create the EmailMessage record should be the relatedTo attribute be defined. The commands' differences are as follows:

  • mail creates the EmailMessage record by itself. The record will not have the MessageIdentifier field defined. It may also require the orgWideEmailAddressData attribute defined for filling in certain field values if an organization-wide address is used. Any files attached to the email through child command attachment will be uploaded to Salesforce and linked to the created EmailMessage record.
  • mail2 lets Salesforce create the EmailMessage record. The record will have the MessageIdentifier field defined and filling in data of an organization-wide address into the record requires no additional attribute to be defined. Any files attached to the email through child command attachment will not appear as linked to the created EmailMessage record (only those attached with recordAttachment do).

Child commands

All the child commands set different properties of the generated email message.

  • to
    Required. Up to 100 recipients may be defined through these child commands, but at least one is required.
  • cc
    Optional. Up to 25 "CC" addresses may be specified through these child commands.
  • bcc
    Optional. Up to 25 "BCC" addresses may be specified through these child commands.
  • replyTo
    Optional. One child command of this kind may be present to set the "Reply-To" header.
  • textBody
    Optional. One child command of this kind may be present to set the message's plain text body.
  • htmlBody
    Optional. One child command of this kind may be present to set the message's HTML body.
  • attachment
    Optional. Any number of file attachments may be added through these child commands as long as the total file size doesn't exceed 10 MB. If the relatedTo attribute is defined and an EmailMessage created, these file attachments are uploaded to Salesforce and their corresponding ContentDocuments then linked to the EmailMessage.
  • recordAttachment
    Optional. Any number of record-based file attachments may be added through these child commands. Any ContentVersion records specified as attachments will also cause their ContentDocuments to be linked to the EmailMessage record generated if the relatedTo attribute is defined.  

Attributes

subject

Required
Value type
EL-evaluated
No String Yes
Defines the subject line of the email message.
senderName

Required
Value type
EL-evaluated
No String Yes
Defines the name of the message's sender. Do note that this only sets the name, not the "From" address.

This attribute may not be defined together with the orgWideEmailAddressId attribute - these two conflict and one of them has to remain undefined.

If not defined, the name set in the active user's Salesforce account appears as the sender. 
orgWideEmailAddressId


Required
Value type
EL-evaluated
No String Yes
Allows the email message's sender name and email address to be set to an organization-wide alias instead of the currently active user's name and email address. The expected value is the ID of an OrgWideEmailAddress record.

This attribute may not be defined together with the senderName attribute - these two conflict and one of them has to remain undefined.

If not defined, the name and email address set in the active user's Salesforce account appears as the sender information.
relatedTo

Required
Value type
EL-evaluated
No String Yes
Allows the sending of the email message to be accompanied by a creation of an EmailMessage record that is linked to the record defined by this attribute. The resolved value should therefore be the ID of a record.

If not defined, no linked EmailMessage record is created.
relatedToWhom

Required
Value type
EL-evaluated
No String Yes
If sending the email causes a Task record to be generated, this attribute defines the WhoId field of that email Task, which links it to a Contact, Lead or User. The resolved value is therefore expected to be the Id of a Contact, Lead or User record.  

If not defined, the generated Task will not be related to any Contact or such.
useSignature

Required
Value type
EL-evaluated
No Boolean Yes
Defines if the email-sending Salesforce user's email signature is included in the sent message.

If not defined, the value of "true" is used, causing the signature to be included.

Examples

The mail command works together with all of its possible child commands in order to produce and send an email message. Note that you can also make use of the basic logic control commands, such as if and forEach, to dynamically alter the email properties.

<mail subject="Test mail">
        <to value="${teamLeader.emailAddress}">
        <forEach value="${teamMembers}" var="teamMember">
          <cc value="${teamMember.emailAddress}">
        <htmlBody value="${composedEmailBody}">
        <if test="${includeDoc}">
          <attachment value="${composedDoc}">