Build-On Tutorial:

Email Templates

Email Templates: Lesson 2

Send Mass Emails

Lesson Overview

The objective for this lesson is to build an email script and layout so your team can mass-email a group of members by choosing and modifying an email template.

You will create two layouts: one for finding members to email, and another layout that is flexible enough to let the user select a template and modify their email before sending. Then you will write a scripted process to handle safely mass-emailing your selected members.

Here is a sneak peek of what you will build:

Step 1 - Add global fields and a summary field

Your mass-email workflow should allow users to select an existing template for their email, then modify it before sending. In order to let them modify what they send without changing the actual template, you will copy the template into editable global fields. Here you will create those fields.

  1. Open the Manage Database dialog (File > Manage > Database...) and activate the Fields tab. Select the z_Globals table in the table dropdown menu.
  1. Create the following new fields in the z_Globals table:
    1. g_Email_Template_Choice_ID (number)
    2. g_Email_Template_Body (text)
    3. g_Email_Template_Subject (text)
    4. For each of these fields, select the Options... button to edit Field Options. On the Storage tab, check the Use global storage (one value for all records) checkbox.
  1. Now you will add a field to the Member table, to collect the email addresses you need for your mass email. Select the Member table in the table dropdown menu.
  2. Create a new field called zz_List_Of_Email, and select Type:Summary.
    1. In the summary options dialog, select List of.
    2. Select the Email field from the Available Fields. (The field will provide a list of emails for a set of records.)
    3. Set Summarize repetitions to All together, then click OK to exit this dialog.
  1. Select OK to close the Options for Summary Field box and select OK to close the Manage Database dialog box.

Step 2 - Create layouts for Email Member List and Template Selection

Duplicate the Member List layout to create a list of members you can email, then create a layout to help users choose a template and set up their mass email.

  1. Open the Manage Layouts dialog (File > Manage > Layouts...).
  2. In the last lesson, you duplicated the Member List layout to create an Email Template List layout. Now you will duplicate it again to create the list view from which your team will find and email members.

    Duplicate the Member List layout by clicking the Duplicate button or by pressing Command-D (macOS) / Control-D (Windows).
  3. Rename the layout to “Email Members” and drag it just below the Member Print layout.
  4. With the Email Members layout selected, click Open to navigate to that layout.
  5. Enter Layout mode using the Edit Layout button in the status toolbar.
  6. Use the Text tool to change the title to “Email Members”. You may need to resize the text object to keep it in a single line.
  7. Remove all buttons except the Print button. Do not forget to remove the invisible button in the background — users will not click on a member to navigate to their details from here.
  8. Change the Label for the Address_Street field to “Email”.
  9. Double-click the Address_Street field and assign it to the Email field. It will help your users if they can correct email addresses right from this list, so with the Email field selected, go to the Data tab of the Inspector and select the checkbox to allow Field entry in Browse mode under the Behavior tab.
  10. Adjust the widths and positions of the fields on the layout so yours looks similar to the image below.

    NOTE: You will rename the Print button to Send Email later in this lesson.

Step 3 - Create layout for selecting an email template

After a user finds members to email, they can select an email template to use. You will build a layout that both allows for the selection of a template and gives the user a copy which they can edit, without editing the original template.

  1. Open the Manage Layouts dialog (File > Manage > Layouts...).
  2. Duplicate the Email Template Detail layout.
  3. Rename the duplicated layout to “Select Email Template Card” by selecting the layout and clicking on the Edit button. Click OK and then select Open to navigate to that layout.
  4. Enter Layout mode, then remove the following items:
    1. EMAILTEMPLATE portal on the left
    2. g_Logo field in the Header
    3. Email Template Detail label in the Body of the layout (not the similar text in the Header)
    4. <<Title>> merge field in the Body
  5. Move the Email Template title text block from the Header into the Body of the layout.
  6. Remove the Header and Footer: click on the handle for the Header, then click Delete. Repeat for the Footer.
  7. Activate the Position tab in the Inspector and select the Body layout part label. In the position tab, set its height to 760 pt.
  1. Now you will create a value list to help the user select a template. Open the File > Manage > Value Lists... menu item.

    1. Create a New value list.
    2. Rename it Email Template ID and Email Template Title.
    3. Select the Use values from field option.
    4. The Specify Fields for Value list window opens.

          1. Select EMAILTEMPLATE for Use values from First field.
          2. Select ID in the left column.
          3. Check the Also display values from second field checkbox.
          4. Select Title in the right column.
          5. Select Include all values, and check the Show values only from second field checkbox.
          6. Confirm your settings and click OK to exit the dialog.
  1. Back on the layout, double-click the Title field. In the Specify Field window select the _GLOBAL table occurrence from the drop-down menu, then select the g_Email_Template_Choice_ID field.
  1. Reassign the following fields in a similar way:
    1. Change the Subject field to g_Email_Template_Subject.
    2. Change the Body field to g_Email_Template_Body.
  2. Select the Description field, and assign the txt disabled.Gray.Left style in the Styles tab of the Inspector. In the Data tab of the Inspector, navigate to the Field Entry area and uncheck Browse Mode, so users will not be able to edit the description. Navigate to the Behavior area and select Hide object when and add a hide condition so that the description does not show up until after you choose a template: 

IsEmpty ( _GLOBAL::g_Email_Template_Choice_ID )

  1. Select the g_Mail_Template_Choice_ID field, and use the Data tab of the Inspector to change the Control Style to Pop-up Menu.
  2. Assign the new Email Template ID and Email Template Title value list to it.
  3. Check the Include arrow to show and hide list and Override data formatting with value list checkbox.
  1. Adjust the widths and positions of the fields on the layout so yours looks similar to the image below.

    NOTE: The Cancel and Send buttons will be added to the layout later in this lesson.
  1. Now you will create a script that will populate the Subject and Body fields when the user selects a different template. Open the Script Workspace and begin by duplicating the Template Script, located in the Example Scripts folder.
    1. Name the script “TRIGGER_Email TemplateID_OnModify”
    2. Move it into the Email Template folder
  2. Modify the script by adding the highlighted steps.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Freeze Window

Set Variable [ $emailtemplate_ID; Value:_GLOBAL::g_Email_Template_Choice_ID ]
Enter Find Mode [ Pause: Off ]
Set Field [ EMAILTEMPLATE::ID; $emailtemplate_ID ]
Perform Find [ ]

Set Field [ _GLOBAL::g_Email_Template_Subject; EMAILTEMPLATE::Subject ]
Set Field [ _GLOBAL::g_Email_Template_Body; EMAILTEMPLATE::Body ]

Go to Field [ _GLOBAL::g_Email_Template_Subject ]

Exit Script [  Result: $null  ]

  1. Save your script, then return to the layout to assign it as a script trigger to the template field. Control-click the ::g_Email_Template_Choice_ID field, then select Set Script triggers...
  1. Select the OnObjectModify checkbox and assign the TRIGGER_Email TemplateID_OnModify script. Click OK to exit the dialog, then save your script.

Step 4 - Adapt existing layouts and scripts for navigation

  1. Continue in Layout mode and navigate to the Desktop > Dashboard layout.
  2. Select the Members button and duplicate it. You can Copy and Paste this button or you can press Option on your keyboard and click and drag the button to obtain a duplicate.
  3. Double-click the newly created button to open the Button Setup window.
    1. Set the label to “Send Emails”
    2. Choose an icon.
    3. Set the optional script parameter to:

         # ( "nav" ; “Send Emails" )

    4. Close the Button Setup window.
  4. Adjust the positions of the buttons so your layout looks similar to the image below.
  1. Use the Layout pulldown menu in the status toolbar to switch to the Desktop > Menu | Card layout.
  2. Double-click on Donation History. Because this is a segment that is part of a Button Bar, the Button Bar Setup window will open.
    1. Click the “+” button to add a Segment to the button bar
    2. Set its label to “Send Emails”
    3. Set Action to: Perform Script
    4. Select the Nav Menu script from the list. You can find it in the General Scripts folder.
    5. Add an optional Script Parameter
# ( "nav" ; “Send Emails" )
  1. Your layout should look similar to the image below.
  1. Open the Script Workspace (Scripts > Script Workspace...).
  2. Open the General Scripts > Nav Menu script, so you can amend it to include the “Send Emails” parameter.
  3. Add the highlighted code to the script, near the end. See the full script below for placement.

Else If [ $nav = "Email templates" ]
  #Email template List
  Go to Layout [ “Email Template List” (EMAILTEMPLATE) ]
  Show All Records
  Perform Script [ “Email Template Go to List” ]

Else If [ $nav = "Send Emails" ]
  #View Member List
  Go to Layout [ “Email Members” (MEMBER) ]
  Show All Records
  Sort Records [ Keep records in sorted order; Specified Sort Order:MEMBER::Member_Name; ascending ] [ Restore; No dialog ]

Go to Record/Request/Page [ First ]

End If

Exit Script [ Result: $null ]

  1. Set the Sort Order to MEMBER::Member_Name, ascending order.

Step 5 - Create email scripts

Now that your basic navigation is ready, you can add the scripts that handle the email workflow. The first script will begin the email and take the user to the Select Email Template Card layout so they can choose a template. A second script will send the mass email.

  1. Open the Script Workspace (Scripts > Script Workspace...).
  2. Create a new script by duplicating the Template Script.
    1. Name the script “Member - Send Email Start”
    2. Move it into the Member folder (this script is called from a member context).
  3. First you will verify that the user has found at least one member, and that at least one member has a valid email address. Modify the script so it contains the following steps:

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Freeze Window

#Verify member found count
If [ Get ( FoundCount ) = 0 // no members in selection ]
   Exit Script [ Result: $null ]
End If

#Verify if all members have email addresses, if not give choice to omit members or cancel the process of sending emails
Set Variable [ $email_count; Value:ValueCount ( MEMBER::zz_List_Of_Email ) ]

If [ $email_count ≠ Get(FoundCount) // no member in selection has an email address ]
   Set Variable [ $message; Value:"One or more members have no email address.¶Do you want to remove them from the email and continue?" ]
End If

# Inform the user about the options if there are members without an email address
If [ not IsEmpty ( $message ) ]
   # There are one or more members without an email address
   Show Custom Dialog [ $message ]

   If [ Get(LastMessageChoice) = 1 // omit members with no email address from selection ]

   Enter Find Mode [ Pause: Off ]
   Set Field [ MEMBER::Email; "=" ]
   Omit Record
   Set Error Capture [ On ]
   Constrain Found Set [ ]
   Set Error Capture [ Off ]

Else If [ Get(LastMessageChoice) = 2 ]
   Exit Script [ Result: $null ]

   End If

End If

  1. The next step is to clear the global fields on the layout so the user has a fresh start, and open the layout. Add the following highlighted steps. Be sure to deselect the Close Window option in the New Window script step settings, so users can only close the window with the scripts you write.

#set global fields for template dialog and show Card window
Set Field [ _GLOBAL::g_Email_Template_Choice_ID; "" ]
Set Field [ _GLOBAL::g_Email_Template_Subject; "" ]
Set Field [ _GLOBAL::g_Email_Template_Body; "" ]

New Window [ Style: Card; Name: "Select Email Template"; Using layout: “Select Email Template Card” (EMAILTEMPLATE) ]

Exit Script [ Result: $null ]

  1. Your final script will look like this:
  1. Now you will create the script to send the mass email. Create a new script by duplicating the Template Script.
    1. Name the script “Member - Send Email Continue ( action )”.
    2. Move it into the Email Template folder
  2. First the script will ensure the user doesn’t want to cancel, then it will validate that the email has contents in the subject and body. Modify the Member - Send Email Continue (action) script to add the highlighted steps.

Allow User Abort [ Off ]
Set Error Capture [ Off ]
Freeze Window

# parse the parameters
Set Variable [ $parameter_parsing_ok; Value:#Assign ( Get(ScriptParameter ) ) ]
If [ $parameter_parsing_ok = False ]
   # parameters could not be parsed, exit this script and report back
   Exit Script [ Result: "error" ]
End If

If [ $action = "cancel" ]
   Close Window [ Current Window ]
   Exit Script [ Result: $null ]
End If

# Verify if subject or body are not empty
If [ IsEmpty ( _GLOBAL::g_Email_Template_Subject ) or IsEmpty (_GLOBAL::g_Email_Template_Body ) ]
   Show Custom Dialog [ Message: "Please enter a subject and body before sending email."; Default Button: “OK”, Commit: “Yes” ]
   Exit Script [ Result: $null ]
End If

  1. Now you will capture the email contents, navigate to a member layout to gather email addresses, and create an email with the list of recipients in the “BCC” area:

# Set variables with data from Card dialog & close window
Set Variable [ $subject; Value:_GLOBAL::g_Email_Template_Subject ]
Set Variable [ $body; Value:_GLOBAL::g_Email_Template_Body ]

# Close Card window dialog > return to Members context
Close Window [ Current Window ]

# Send emails for found set
Go to Record/Request/Page [ First ]

Set Error Capture [ On ]

Send Mail [ Send via E-mail Client; With dialog: On ; BCC: MEMBER::Email; Subject: $subject; Message: $body ]

Set Variable [ $error; Value:Get ( LastError ) ]
Set Error Capture [ Off ]

 

  1. The Send Mail step set up window should look like this:

    Note: Make sure to select Collect addresses across found set.
  1. If there was an error with the email, the script should address that. Then the script will create a new Interaction record for each member in the list, logging that they were sent the email. Add the highlighted script steps:

If [ $error = 0 // sent successfully ]
    # create ID list for creating interactions
    Set Variable [ $memberID_list; Value:MEMBER::zz_ListOf_ID ]

Else
    Show Custom Dialog [ Title: "Error"; Message: "An error has occurred and your emails were not sent."; Default Button: “OK”, Commit: “Yes” ]
    Exit Script [$null]

End If

# if sending emails was successful, add Interaction records
If [ not IsEmpty ( $memberID_list ) ]

   Set Variable [ $note; Value:"Email Sent: " & Trim($subject) ]
   New Window [ Style: Document; Name: "Add Interactions"; Using layout: “Interaction_DEV” (INTERACTION) ]

Loop
      New Record/Request
      Set Field [ INTERACTION::ID_member; GetValue ( $memberID_list ; 1 ) ]
      Set Field [ INTERACTION::Type; "Email" ]
      Set Field [ INTERACTION::Summary; "Email sent to Members" ]
      Set Field [ INTERACTION::Note; $note ]
      Commit Records/Requests [ With dialog: Off ]
      Set Variable [ $memberID_list; Value:RightValues ( $memberID_list ; ValueCount ( $memberID_list )-1 ) ]
   Exit Loop If [ ValueCount ( $memberID_list ) < 1 ]
   End Loop

Close Window [ Name: "Add Interactions"; Current file ]

End If

Exit Script [ Result: $null ]

  1. Your finished script should look like this:

Step 6 - Add buttons and assign scripts

The final step is to assign the email scripts to existing or new buttons on your layouts.

Navigate to the Email Template List layout.

  1. Enter Layout mode using the Edit Layout button in the status toolbar.
  2. Select and Copy the New Template button (Edit > Copy), then navigate to the Select Email Template Card layout.
  3. Paste the button on the layout (Edit > Paste).
  4. Double click on the button and in the Button Setup dialog, set the following properties for the button:
    1. Set the button name to “Send”
    2. Select the Member - Send Email Continue ( action ) script and close the Button Setup dialog.
    3. Change the Autosizing options to anchor bottom and right on the Position tab in the Inspector.
  1. Select and duplicate the Send button (Edit > Duplicate). Double click the duplicated button and in the Button Setup dialog, set the following properties for the button:
    1. Set the button name to “Cancel”
    2. Set the optional script parameter to the following and then close the Button Setup dialog:

# ( "action" ; "cancel" )

  1. Apply the btn White style to this button via the Stytes tab in the Inspector and place it to the left of the Send button.
  2. Position the Send and Cancel buttons so that your layout looks similar to the image below.
  1. Now navigate to the Email Members layout.
  2. Double-click the Print button.
    1. Change the button name to “Send Email”.
    2. Select the Member -Send Email Start script and then close the Button Setup dialog.

Step 7 - Review your work

Now you can test the entire mass email Build-On!

  1. Navigate to the Email Members layout, and use native FileMaker search functions to find the group of members you want to email.  
  2. Ensure the list of members includes valid email addresses. For testing purposes, it is a good idea to limit your tests to your own email address(es) and those of your colleagues.  
  3. Begin an email for the found set of members by clicking on the Send Email button. Doing this should open the card window where you can choose an email template from the pop-up menu.  
  4. Selecting an email template should fill the global fields with the data available in the template.  
  5. Change the subject or body of the email. The template should not change.
  6. Test both Cancel and Send from the email screen. This will close the card window. Depending on your choice, the action will be canceled or the emails will be sent and an interaction will be created on each member’s record from the found set.