This example sends a mass mail including global attachments with a subject, body, header, and footer that is unique for each recipient. Since the attachments are the same for every recipient, the scripting of this database takes advantage of the plug-in’s ability to cache parts of an email, to speed up the sending. To take advantage of this, the script attaches the files once at the beginning of the script, instead of inside the loop for every email.
Download Example File
- Before you can send email from this database, you will need to enter a few settings. At bare minimum, you will need to enter your email host. The default host port is 25, but you may need to change this depending on your email server. If your email server requires authentication, you will need to choose an authentication type and enter your username and password. If your email server requires an SSL connection, you can set the SSL field to the correct SSL type. If you are unsure of which type to use, try both to see which works.
SMTPit Pro will always return information back to you when you make a function call. You can also get a transcript of of the interaction between SMTPit Pro and your mail server by setting the field “Get Transcript” to true.
All of the fields mentioned above are used in various calculations throughout the example database. This approach allows the database to be portable in a sense because the database can be moved to a different computer without losing the settings.
Another approach for storing settings is to use the default values in the SMTPit Pro configuration dialog. In the configuration dialog you can add default headers and footers, and other various settings. These preferences will be stored on your computer only, so if you move a database to a different computer, you will need to visit the preferences dialog to enter your settings. There are advantages to using both methods, and it will be up to you to decide which one will fit your needs.Need help? Don't know what to use as your Settings or getting errors when trying to send?
Take a look at this article.
Access the Plug-in
When using plug-ins (not just ours), they do not add new script steps, but instead add new functions that are available in the calculation engine.
To see a calculation that tells the plug-in what to do, go to the “Scripts” menu, and choose “Manage Scripts” or “ScriptMaker”. Once in Manage Scripts/ScriptMaker, double click on the “Send” script. Note that we are using the “Set Field” script step which consists of two settings. The “Specify target field” button allows you to choose which field you want to set. In our case we want to set the “Result” field. The second specify button is where the SMTPit Pro calculation exists. Click this button to see the calculation used to tell the plug-in what to do.
In this calculation, the plug-in is accessed using the “SMTPit_FunctionName” functions. There are many functions allowing you to do different things such as set the To address, Subject, and etc. For a complete listing of the functions available, see the Functions tab. You can also access the functions in a “Specify Calculation” window by clicking the “View” menu, then selecting “External Functions”, and then scrolling through the list until you find the plug-in name.
Prepare the Email
Before you can send the email, you need to add recipients, attachments, and the email body.
To setup your recipients that will receive your mailing, click the Edit Addresses button. Enter the names and email addresses of your recipients. Alternatively, you can use FileMaker’s “Import Records” on the File menu to import the data from an external source. The ID field is automatically entered when a record is created, and this number is included in the headers of each email. This is done for easier tracking of any bounced emails after a mailing. The Product field allows you to enter some unique data for each recipient. When the recipients receive the email, the data in the email will reflect the data in the recipient record. You could easily add more fields, but for this example we only included one. Once a mailing is complete, you can check the Send Result field for each recipient to verify all the emails were sent successfully. Close the pop-up window when done editing your recipients.
To add attachments, click on the Edit Attachments button. You can add attachments to the three container fields and/or the three path fields. To import a file into a container field, right click on the field and select one of the Insert options. To use a path to a file, click a Locate File button and browse to the file. You can use any number and combination of files either from container fields or on your hard drive. Close the pop-up window when done editing your attachments.
Finally, you need to setup the email and send it. In the From field set the address the email will be coming from, and the email subject in the Subject field. The Header, Body, and Footer fields will contain the actual content of your email. Make sure to do this for both the Text and HTML tabs, since any recipient that cannot view HTML will see the Text part. You can add data from other fields in your database using the merge field syntax (e.g. <<Email::Name>>). When the email is sent, the plug-in will replace the merge field syntax with the data from the field in the current record. Once you are done setting up the email, click the “Begin Mass Mail” button to start the mailing.
This example has a Send Result field where the Results are shown. This is where the plug-in can give you feedback on what it is doing. If an error occurs, it will report the error in the results field which can help you fix any issues you may be having. It will also report its successes so that you know everything is going as planned. If you have “Get Transcript” set to true on the settings layout, you will also see the interaction between SMTPit Pro and your mail server in the Result field.Need help? Getting errors when trying to send?
Take a look at this article.
Send Mass Mail Script
To understand how this example works, open ScriptMaker/Manage Scripts and edit the Send Mass Mail script.
Set Field[Email::Start Timestamp; Get ( CurrentHostTimeStamp )] Set Field[Email::End Timestamp; “”]
The script starts by setting the starting timestamp and clearing the ending timestamp fields. This is not required for a mailing, but can be helpful if you want to know how long it took to send all the email.
If[IsEmpty(Email::Host) or Email::Host = “mail.yourdomain.com”]
This If statement simply checks the Host field to make sure the user entered their own mail server address or did not leave it blank. By default, “mail.yourdomain.com” is what the Host field contains (we put this in the field to give users an idea of what should go there upon initial setup). This is not required, but may help eliminate simple mistakes.
Show Custom Dialog["Message"; "Please enter your mail server settings on the Settings layout."] Perform Script["Edit Settings"] Set Field[Email::Start Timestamp; ""] Halt Script End If
This tells the user there was an error, calls the “Edit Settings” script which opens the window to edit the host settings, clears the starting timestamp, and finally halts the script.
Set Field[Email::Setup Result; “// Clear all values from previous message SMTPit_Clear & “¶”…”]
This step begins setting up the email within the plug-in using the plug-in’s functions. Select the Set Field step and click the Calculated result ‘Specify…’ button. A new window will open with a calculation.
// Clear all values from previous message SMTPit_Clear & “¶” &
This part clears all current settings within the plug-in. This is done in case you previously sent an email and did not want to retain any settings from that email. When you set a part of an email within the plug-in, it will keep that value until you change it, clear it, or close FileMaker. Note, the two “//” forward slashes indicate a comment within a calculation in FileMaker. The data after the forward slashes is ignored by FileMaker and allows you to make human readable notations.
The ‘& “¶” &’ after SMTPit_Clear is simply for formatting purposes. Alternatively, you could just use a single ampersand ‘&’, but adding the paragraph mark makes your result field easier to read. When you call a function of the plug-in it will return (in the field you are setting) a ‘result’, whether it is a success or an error. If the paragraph marks are omitted from between functions, the result field would contain all the data on one line and be harder to read.
// Set up host, authentication, and from address SMTPit_SetHost( Email::Host ) & “¶” & SMTPit_SetAuthentication( Email::Authentication Type ; Email::Username ; Email::Password ;Email::UseSSL ) & “¶” & SMTPit_SetFrom( Email::From Address ) & “¶”
Continuing with the calculation, the SMTPit_SetHost function is set with the mail server address from the Email::Host field. The SMTPit_SetAuthentication function is then set with the authentication type, username, password, and SSL option from the associated fields. Finally, the SMTPit_SetFrom function sets the from address using the data in the Email::From Address field.
If ( IsEmpty(Email::Attachment1); “”; SMTPit_SetAttachment( Email::Attachment1) ) & “¶” &
This sets the first attachment from the Email::Attachment1 field. The If statement checks if the Email::Attachment1 field is empty, and if it is not, then it will set it as an attachment using the SMTPit_SetAttachment function. If you removed the If statement, and the field was blank, the SMTPit_SetAttachment function would return an error. That would be acceptable if you wanted to make attachments required for an email, but for this example they are not.
If ( IsEmpty(Email::Attachment2); “”; SMTPit_SetAttachment( Email::Attachment2; SMTPit_Append ) ) & “¶” & If ( IsEmpty(Email::Attachment3); “”; SMTPit_SetAttachment( Email::Attachment3; SMTPit_Append ) ) & “¶” & If ( IsEmpty(Email::Attachment4); “”; SMTPit_SetAttachment( Email::Attachment4; SMTPit_Append ) ) & “¶” & If ( IsEmpty(Email::Attachment5); “”; SMTPit_SetAttachment( Email::Attachment5; SMTPit_Append ) ) & “¶” & If ( IsEmpty(Email::Attachment6); “”; SMTPit_SetAttachment( Email::Attachment6; SMTPit_Append ) ) & “¶”
This continues setting up the rest of the attachments from the other attachment fields. Notice the second parameter of the SMTPit_SetAttachment function is “SMTPit_Append”. Adding this parameter appends the attachment to the plug-in’s internal list of attachments already assigned. If this parameter was not used, the second attachment would overwrite the first, then the third attachment would overwrite the second, and etc. The result would be an email with one attachment which was the last file attached, since each call overwrote the one before it. So, if multiple attachments are needed, always use the SMTPit_Append parameter.
Click the OK button to close the calculation window and continue looking at the script.
If[PatternCount( Email::Setup Result; “ERROR:”) > 0]
This If statement checks the Email::Setup Result field for errors. This is the same field we have been setting all our plug-in functions to because they will return errors into this field if one occurs. PatternCount is a FileMaker function that returns the number of occurrences of a search string in the specified text. In this case, we are searching the Email::Setup Result field for “ERROR:” because the plug-in will always return errors in this format. If the PatternCount returns a number greater than zero, the If statement will be true. Please note, error checking such as this is very important in your scripts. If you ignore errors the plug-in returns, it will not work as expected, and compound problems in the future.
Show Custom Dialog[Title: “Message”; Message: "There was an error setting up the email…etc] Set Field[ Email::Start Timestamp; “”] Halt Script End If
This will display a message that there was an error, clears the starting timestamp, and Halts the script.
Set Field[Email::Setup Result; Email::Setup Result & “¶¶” & SMTPit_Connect( Email::GetTranscript )]
This Set Field calls the SMTPit_Connect function to make the plug-in connect to your mail server. Notice the calculation of it sets the field to itself and then calls the SMTPit_Connect function. This is done to append to the field, so any data in the field previous to this step will be retained and not overwritten.
If[PatternCount( Email::Setup Result; “ERROR:”) > 0]
This checks the Email::Setup Result field again to see if any errors occurred during the SMTPit_Connect function.
Show Custom Dialog[Title: “Message”; Message: "There was an error connecting. Please check…etc] Set Field[ Email::Start Timestamp; “”] Halt Script End If
As before, this will display a message that there was an error, clears the starting timestamp, and Halts the script.
Go to Record/Request/Page [First] Loop
This step goes to the first record in the table and then enters the Loop to begin the mailing
Set Field[ Email::Send Result; Email::Send Result & “¶¶” & etc…]
This sets up the email for the current record’s recipient. Select the Set Field step and click the Calculated result ‘Specify…’ button. A new window will open with a calculation.
SMTPit_SetSubject( Email::Subject ) & “¶” &
This sets the email subject from the Email::Subject field.
SMTPit_SetTo( If ( IsEmpty(Email::Name); Email::Email; “"” & Email::Name & “"” & " <" & Email::Email & ">" ) ) & “¶” &
This sets the To address for the current email. The If statement is not necessary, and just puts a human readable name at the beginning of the address ( e.g., “Bob Smith” <email@example.com>). The If statement is saying, if the Email::Name field is empty to use just the email address, otherwise it will format the human readable name and email address together in the correct syntax. Notice the " inside the If statement. FileMaker requires this syntax when you want to place a double quote inside static text. This is needed because double quotes are the normal delimiters around static text. For example, using “My static text” in a Set Field would result in those words in the field without double quotes around it. However, if you wanted to put “My “static” text”, you would have to use the syntax mentioned previously (e.g., “My "static" text”).
SMTPit_AddEmailHeader( “X-RecID=” & GetAsText ( Email::ID ) )]
This function adds an email header to your email. This is different from a body header in that it shows up in the area where things like the email’s Subject and Date appear in a received email. Each record in the database has a unique ID in the Email::ID field. This is added to the email in the headers to help with bounced emails. When you receive a bounced email, most mail servers will return the headers from the original email you sent. Having this in the headers will help you find the bounced email address in your database and take the necessary action on it. You could also set up a database that receives your bounced emails and attempts to automatically remove problem email addresses based on this ID. However, not all email servers will return the original headers, so setting up a completely automated system like this is not an easy task.
// Set up Text and HTML Body, Header, and Footer SMTPit_SetBody( Email::TextBody; “Text”) & “¶” & SMTPit_SetBody( Email::HTMLBody ; “HTML” ) & “¶” &
The first SMTPit_SetBody function sets the Text body with the data from the Email::TextBody field. The second SMTPit_SetBody function then sets the HTML body from the Email::HTMLBody field. Notice the second parameter is different in each function. This is what determines if you are setting the Text or HTML body. Setting both the Text and HTML body makes the plug-in send a Multi-part email. In other words, an email that will contain both a Text and HTML part, so if a recipient’s email client (such as Outlook, Eudora, etc.) cannot view HTML, they will see the Text part.
SMTPit_SetBodyHeader( Email::TextHeader ; “Text” ) & “¶” & SMTPit_SetBodyHeader( Email::HTMLHeader ; “HTML” ) & “¶” &
These two functions set the Text and HTML body headers from the associated fields. The SMTPit_SetBodyHeader works the same as the SMTPit_SetBody function. Again, the second parameter determines if you are setting the Text or HTML body header.
SMTPit_SetBodyFooter( Email::TextFooter ; “Text” ) & “¶” & SMTPit_SetBodyFooter( Email::HTMLFooter ; “HTML” )
Finally, these set the Text and HTML body footers from the associated fields. Notice the second SMTPit_SetBodyFooter function does not have ‘& “¶” &’ on the end because there are no additional functions after it.
Click the OK button to close the calculation window and continue looking at the script.
Set Field[ Email::Send Result; SMTPit_Send & “¶” & Get ( CurrentHostTimeStamp )]
This step sends the email using the SMTPit_Send function. The Get (CurrentHostTimeStamp) is a FileMaker function and is not required to send an email. This was added so the Email::Send Result field will have the exact date and time an email was sent.
Go to Record/Request/Page [Next; Exit after last] End Loop
This goes to the next record and then exits the loop after the last record in the table.
Set Field[Email::Setup Result; Email::Setup Result & “¶¶” & SMTPit_Disconnect( Email::GetTranscript )]
This step calls the SMTPit_Disconnect function to disconnect the plug-in from the mail server. The parameter of the function allows you to get a transcript of the interaction between the plug-in and the mail server. The parameter takes a Yes or No and gets this data from the Email::GetTranscript field. This is an optional parameter and is not required to use the function.
Set Field[Email::End Timestamp; Get ( CurrentHostTimeStamp )]
This sets the ending timestamp field, but is not required for a mailing.
Show Custom Dialog[ Title:“"Mass Mail \"" & Email::Subject & "\" Completed"*/”; Message: "Start Time:…etc]
Finally, this shows a dialog that reports the time it took to complete the mailing. Again, this is not required for a mailing.
How to recreate in your solution
After you have gone over the example databases, learned how they work and how the plug-in works, you can integrate the plug-in into your own solutions. There are many ways this can be done, but here are a few of the most common ways.Note, to properly integrate the plug-in into your own solution you need to be proficient at FileMaker scripting and calculations. While our documentation tries to provide some tips, teaching all the ins and outs of FileMaker scripting and calculations is beyond what we do. FileMaker offers many training options to help you further your FileMaker developing skills. If you are looking for a professional developer to integrate the plug-in into your solution, you can search for one on FileMaker's Consultants site.
Import example script
This is the easiest way to go, but can be the most frustrating at the same time. When importing a script, you will have to go back over the imported script with a fine tooth comb. Field references will be different between the example database and your own database, so you will have to touch every script step to make sure all field references are correct. This will mainly deal with the Set Field script step (but check all the script steps to make sure they are correct for your database). Select the Set Field step and check the “Specify target field” button to make sure that field is correct. Then check the “Calculated result” button and make sure any field (and table names) are correct. If you find /* */ at the beginning and end of the calculation, FileMaker has commented out the code because of incorrect field references. You will need to fix all field references, and then remove the /* */ from the beginning and the end.
Re-create example script
Print out or view the example script and re-create it in your own database. Since you will be creating the script as you go, you are less likely to overlook an incorrect field reference as you would with Importing an example script. This method helps you to better understand what your script is doing since you are actually creating the script yourself.
Create script from scratch
If you went over all the example databases, you should have a pretty good idea what a script would look like. Using the function browser to give you more information about the functions, you can create a script to send an email exactly as you need it. Click the “Functions” tab to open the function browser. Remember to build error checking into your scripts. This is very important and will save much frustration later when something stops working and you have no idea why and no errors to go by.
Be sure to check out the Coding Considerations section for some helpful tips on working with the plug-in functions and writing scripts.