To test the example, you will first need to enter your mail server information by clicking the Settings button. The Host name is the address for your mail server (such as mail.yourdomain.com). Enter your authentication details unless your mail server specifically does not use authentication. You may need to contact your mail server administrator to find out the type, username, password, and whether to use SSL or not. The Transcript field allows you to get the interaction between the plug-in and your mail server when you send an email. Generally this is only needed when troubleshooting a problem when sending email. Close the pop-up window when done editing your mail server information.

Now you need to setup your recipients that will receive your mailing 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. 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.

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 Setup 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. The Send Results field will show you the results for each individual email. 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 and edit the Send Mass Mail script.

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.

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.

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.

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.

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.

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.

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.

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.

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.

This will display a message that there was an error, clears the starting timestamp, and Halts the script.

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.

This checks the Email::Setup Result field again to see if any errors occurred during the SMTPit_Connect function.

As before, this will display a message that there was an error, clears the starting timestamp, and Halts the script.

This step goes to the first record in the table and then enters the Loop to begin the mailing

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.

This sets the email subject from the Email::Subject field.

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" <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").

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.

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.

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.

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.

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.

This goes to the next record and then exits the loop after the last record in the table.

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.

This sets the ending timestamp field, but is not required for a mailing.

Finally, this shows a dialog that reports the time it took to complete the mailing. Again, this is not required for a mailing.