FileMaker 7–11 Example

FileMaker 12 Example

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.

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.

Before you can start the mass mail, you need to setup your recipients that will receive your mailing. Do this by clicking 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. 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 tag (e.g. <<Email::Name>>). When the email is sent, the plug-in will replace the merge field tag 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.

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 and authentication 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 from address is set with 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.

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 ) & “¶” & SMTPit_SetTo( If ( IsEmpty(Email::Name); Email::Email; “"” & Email::Name & “"” & " <" & Email::Email & ">" ) ) & “¶” &

The first function sets the Subject from the Email::Subject field. The SMTPit_SetTo function then sets the To address for the current email. The If statement is not absolutely necessary, as it just puts a human readable name at the beginning of the address ( e.g., “Bob Smith” <bob@domain.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.

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.

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.