Contact us Blog

Email generation step-by-step

Prerequisites

To use the mail merge tool, please make sure the Apsona configuration for your profile (described here) includes the access to the following Salesforce objects.

Preparing your email template

Apsona can use as email template any of the templates available when you click Setup - Communication Templates - Email Templates in Salesforce. Apsona can use either plain text or HTML templates. Note that template merge field names are surrounded by double curly braces and can contain alphabets, numerals or underscores, but may not include any other characters (such as punctuations or embedded spaces) in them. For example, {{CustomerName}} is a valid merge field name, but {{Street Address}} is not (because of the embedded space).

Template attachments

Salesforce lets you create attachments to email templates, so that you can attach to an email any non-dynamic file such as data sheets, white papers or prospectuses – content that isn't personalized for the email's recipient. To attach such a file to an email template, find the template in Salesforce via Setup - Communication Templates - Email Templates, scroll down to the bottom and use the "Attach File" button as shown in the animation below.
If you select "My Computer" in the File Location dropdown, the file is attached directly to the email template. When such an email template is used, Apsona picks up its attachments and includes them with each email that is sent out.

One caveat here: Apsona does not support attachments linked to the Document object or the folders in Salesforce – it only supports attachments uploaded via the "My Computer" choice in the File Location dropdown.

Generating email messages without attachments

Select and run the report for the email merge

Select and run the report. In this example, we have selected an Opportunity Contact Role report from which we obtain the email addresses of the contacts to whom to send email.

Selecting a subset of records from a report

Once the report is run, you can select one or more rows from the report result using either click, shift-click or ctrl-click. With such a selection, each selected row will generate one email message. If you do not make such a selection, all of the rows in the report will be used, and each row will generate one email message.

Set the merge options

Here you can select the type of action you need. In this example, we will select Email merge, and click the Next button. Notice that the popup shows the number of records to be processed.

Set template-related options

  • In the "Email template" selector, select the email template to use. All the email templates stored under Communication Templates in Salesforce will be shown in this dropdown.
  • In the "Email address field" selector, select the field or column containing the recipient's email address. This dropdown displays all email or text fields in the object or report from which you are sending the emails. Thus each data record produces one email message to be sent to the address contained in the field you select here.
  • In the "Cc email address field" selector, optionally select the field or column containing the CC recipient's email address. If you select a field here, the generated message will be cc'ed to the email address(es) in the field. The field must contain either a single email address, or multiple email addresses separated by commas, semicolons or spaces.
  • The "Sender" dropdown lets you choose the name and email that the recipient of your email will see as the origin of the email. The default value is always the name and email of the user who runs the merge action. If you wish, you can set up org-wide email addresses, and any such addresses will be available as options in the dropdown. For example, you might use this feature if you want all emails to appear as having been sent from The CEO <ceo@mycompany.com>, regardless of which user actually sends the emails.
  • Enter an email address in the Reply-to box. This email address will be used as the "reply-to" field in all the outbound email messages.
  • Optionally, you can provide CC and BCC addresses. Within the CC address box, you can provide a list of email addresses separated by commas, and if you do so, all of those email addresses will be CC'ed on every email sent. Similarly any addresses in the BCC box will be BCC'ed on every email message.
Click Next.

Match merge fields

On the left you will see all the merge fields available in the selected email merge template. Each merge field should be matched with a corresponding data field in the report. Click Next.

Set options for logging

In Step 4 of the merge wizard, you can select a few different logging options specifying what will happen each time the merge is executed. You can select one or more logging options, or none at all. The merging process checks for any errors that might have occurred in sending the email. For example, if a record has a malformatted email address, then the email cannot be sent. In such a case, the logging action will not be taken for that record; in other words, the logging actions will be taken only for those records for which Salesforce indicates a successful email transmission. Note, though, that this does not mean that all the emails were successfully delivered; for example if an email address looks valid but points to a non-existent domain or one whose mail server is down, or if the mail server refuses the email, the message will not be delivered even though Salesforce has indicated success.

Testing your merge action

The Test only check box can be used if you need to test a template. Enter an email address in the box. If you choose this option, all the generated emails will be sent to the email address you specify, regardless of the actual email addresses in the data records. You can use this to test your merge templates.

Note, though, that setting the test-only checkbox will only (temporarily) affect the To address of the emails being sent out. It does not affect the Cc or Bcc settings in your merge action. Therefore, when testing your merge action, it is best to use a small set of records with known To, Cc and Bcc email addresses. (See above directions for how to select a subset of records from a report.)

Download results

You can click the Download results button to see the result of each record in the email merge batch. If the email was successfully sent to the recipient it will show as Success. If the email was not sent to a particular record that will be recorded as well.
Click close.

Email messages with generated attachments

You can also send email messages with personalized content in the email body as well as a personalized attachment. The attachment can be either a .docx or a .pdf file. To do this, use the four-step
  1. Select "Email and document merge" as the action in the first step of the merge action popup. Click Next.
  2. In this step, specify the document template (used for the attachment) and the email template (used for the email body). In the Document template selector, Apsona displays all the .docx files available in the Document object in Salesforce. In the Email Template selector, Apsona displays all the email templates available in Salesforce (the ones displayed via Setup - Communication Templates - Email Templates).

    Notice that In the Document merge options area, you can select a field to use as attachment name. This gives you a way to provide a customized name for the attachment to each sent email. For example, when sending a document to your vendors, you might want the attachment to be named something like "Acme Corp.docx" where Acme Corp is the name of the recipient company. To achieve this, you specify a field in your data source - e.g., the Account Name field - as the one that provides the attachment name.

    If you run the merge action from a report, you can create a calculated value in the report and use it for producing the attachment name. This way, your attachment names can be customized to your exact needs, e.g., Acme Corp - Purchase Order - Jan 2017.pdf.

    Click Next.

  3. In Step 3, you set up the mappings between the fields in your data sources and the merge fields in your templates. This step is similar to the one for simple email merges, except that there is a "Document template" section as well as an "Email template" section for setting up the mappings in each of the templates.

    After setting up the field mappings, click Next.

  4. Finally in step 4, you can set up any options you need for logging to occur each time the merge action is run.

Troubleshooting

The Email Address Field dropdown is empty in step 2 of the merge builder popup

The Email Address Field dropdown contains the names of all the fields of data type email in the data source. For example, if you are running the merge from the Contact object, the dropdown might contain the Email, Personal Email and Work Email fields. But if merging from an object that has no email fields (e.g., Opportunity), the dropdown will be empty. In this case, you will need to create a single-step or multi-step report that extracts the necessary Email fields from related objects, and use that report to generate your document.