This example demonstrates a way to throttle a mass mailing sent from SMTPit Pro. Many Internet Service Provider (ISP) email servers only allow you to send X amount of email in Y amount of time, so this example database will help your mailing comply with this requirement. For more complex mass mailing examples, check the Example Library site often or subscribe to one of our RSS feeds for updates.
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.
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 ( CurrentTimeStamp )] 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.
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.
Show All Records Go To Layout [“Text”] Set Field [Email::Total; Get ( FoundCount)]
This first shows all records, goes to the layout named “Text”, and then saves the total number of records in the Email::Total field. This number will be used later to determine when to exit the sending loop.
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
Perform Script [" Send"]
This step calls the “Send” script which does the actual email sending. To look at the “Send” script, close the current window which will take you back to ScriptMaker. Select the “Send” script and click edit.
Set Field [ Email::Counter; 0 ]
The first step sets the Email::Counter field to zero. This field will keep track of how many emails have been sent in the current “set”. The term “set” refers to the number of emails you specified to be sent in X amount of time on the Settings layout.
Set Field [ Email::ConnectionCounter; 0 ]
This sets the Email::ConnectionCounter field to zero. This field will keep track of how many emails have been sent on the current Connection. This will only apply if you have set the number of emails per connection option to a value greater than zero on the Settings layout.
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 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 an error message, clears the starting timestamp, and Halts the script.
Loop Set Field [ Email::Counter; Email::Counter + 1 ] Set Field [ Email::ConnectionCounter; Email::ConnectionCounter + 1 ]
This enters the Loop and then increments both counter fields.
Set Field [ Email::Send Result; Email::Send Result & “¶¶” & etc…]
This step begins setting up the current email 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.
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 ( CurrentTimeStamp )]
This step sends the email using the SMTPit_Send function. The Get (CurrentTimeStamp) 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.
Exit Loop If [ Email::Counter = Email::Throttle or Get ( RecordNumber ) ≥ Email::Total ]
This step exits the loop if the throttle count has been reached or all the email has been sent out. The Email::Counter field contains the number of emails that have been sent in this “set”, and the Email::Throttle field contains the value you set on the Settings layout. The Get ( RecordNumber ) function is used to see what record (out of all the records in the database) the script is on and compares that to the total number of records which is contained in the Email::Total field.
If [ Email::Connection > 0 and Email::ConnectionCounter ≥ Email::Connection ]
This If statement checks to see if the Email::Connection field was set to a number greater than zero and if the email connection counter field, Email::ConnectionCounter, is greater than or equal to the Email::Connection field. As mentioned previously, the Email::Connection field contains the number of emails to send per connection as set on the Settings Layout. The Email::ConnectionCounter field is tracking how many emails have been sent on the current connection. When the number of emails in the current connection equal or exceed the number you set on the Settings layout, the script will disconnect and then reconnect. If the field was set to zero (the default value), the If statement will be false so this portion of the script would be skipped.
Set Field [ Email::ConnectionCounter; 0 ]
The step resets the Email::ConnectionCounter field to zero because the script will be opening a new connection and need to count the number of emails until the next reconnect.
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.
Pause/Resume Script [ Duration (seconds): 1 ]This step pauses for one second between disconnecting and connecting. This probably is not needed, but was just added to give the mail server a second before continuing with the mailing.
Set Field [ Email::Setup Result; Email::Setup Result & “¶¶” & SMTPit_Connect( Email::GetTranscript ) ]This calls the SMTPit_Connect function to open the connection to the mail server again.
If [ PatternCount( Email::Setup Result; “ERROR:”) > 0 ]Since the script is trying to connect to the mail server again, we need to check for errors to make sure it successfully connected. This step checks the Email::Setup Result field for “ERROR:” because the plug-in always returns errors with this syntax.
Show Custom Dialog [ Title: “Message”; Message: "There was an error connecting. Please check the Setup Result…etc] Set Field [ Email::Start Timestamp; “” ] Halt Script End If End IfThis will display a message that there was an error, clears the starting timestamp, and Halts the script.
Go to Record/Request/Page [Next]This step goes to the next record.
End LoopThis is the closing of the loop.
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. Once the script reaches this point it will go back into the “Setup Mass Mail” script.
Close the " Send" script window and then select “Setup Mass Mail” in the ScriptMaker window and edit it. Find the following script step.
Exit Loop If[Get ( RecordNumber ) ≥ Email::Total ]This step exits the loop if all the email in the database have been sent.
Pause/Resume Script[Duration (seconds):Email::Wait * 60]This step will pause the scrip for the amount of minutes that you specified on the Setup layout. The Pause/Resume script step requires time in seconds, so the value contained in the Email::Wait field, which is specified in minutes, is multiplied times sixty to get the number of seconds to pause.
Go to Record/Request/Page [Next]After the script pauses for the amount of time, it will go to the next record and then go back into the " Send" script to continue sending email.
End Loop Set Field[Email::End Timestamp; Get ( CurrentTimeStamp )]
This is the end of the loop and when it is completed will set the ending timestamp field. The “Duration” calculation field will then show the amount of time it took to send the entire mailing. This is not required for a mailing, but may be useful information to know how long it took to send all the email.
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.