Using the plug-in

Before you begin integrating the plug-in into your database, you need to make a couple of decisions on using plug-in. This includes how you will access the plug-in as well as a download method.

Access Method

Beginning with FileMaker Pro 16, plug-ins can have their own script steps in addition to the normal external function calls plug-ins have always used. With POP3it Pro 5.5 and higher, the plug-in adds these script steps to work with the plug-in, which is considered the “Basic” method to access the plug-in. All versions of the plug-in include the external function calls, which is considered the “Advanced” method to access the plug-in. Below are the advantages and disadvantages for each method of accessing the plug-in.

Script steps

• Easy to implement
• Requires less knowledge of FileMaker calculations
• Only available in FileMaker Pro 16 and above and POP3it Pro 5.5 and above
• Less versatile

External Functions

• Provides most flexibility
• Available in all versions of FileMaker and the plug-in
• More complex to setup over the script steps
• Requires proficiency in FileMaker calculations

How you access the plug-in depends on what you are trying to accomplish as well as your proficiency in FileMaker. You can also combine both methods by using script steps in combination with external functions so you are not committed to using just one method.

Download Method

After deciding between script steps and external functions, now you need to determine which download method you will use to download email into your database.

Basic Downloading

The basic downloading method uses the Check Account function or script step to download email. This requires a single call to the POP3it_CheckAccount function or the POP3it Check Account script step and takes care of the entire process of connecting to the mail server, downloading email and attachments, and then disconnecting. This is the simplest way to use the plug-in, but provides less flexibility over the advanced downloading method.

The Check Account function/script step keeps track of what email has been downloaded by storing a file on your computer. Because of this, if you download email using Check Account from more than one computer using the client plug-in, you may get duplicate email in your database. If you need to check email from multiple computers, please use the advanced downloading method below. Alternatively, the server plug-in can be installed on FileMaker server and have it download email instead of using the client plug-in on multiple FileMaker Pro client computers.

To implement Check Account, you need to:

• Create a script that calls the POP3it_ConfigureAccount function or the POP3it Configure Account script step. Alternatively, you can use the Account functions to programmatically create/edit accounts. If you are using the server plug-in, you must use the Account functions. See the Accounts Configuration page for more information.
• Run the Configure Account script and create an email account within the plug-in
• Create a script that calls the POP3it_CheckAccount function or the POP3it Check Account script step.
• Run the Check Account script. The plug-in will create the tables for email and attachments
• Run the Check Account script again and email will begin downloading

For examples of implementing Check Account, see the Integrate POP3it Pro Into a Database, Receive Email, or the Receive Email (Script Steps) example databases.

Advanced Downloading

The advanced downloading method gives you complete control over the entire download process using the plug-in’s Advanced functions. This means your script will need to connect to the mail server, check for email and decide if that email needs to be downloaded, create records to hold the email, and then disconnect. This requires much more scripting over the Basic method, but gives you complete control over the entire process. For example, if you wanted to only download email that contain a specific subject or even only download specific types of attachments, this method provides that type of granular control. However, this does require more knowledge of FileMaker scripting and calculations, so it is suggested for more experienced FileMaker Developers.

Unlike the basic download method, the advanced download method requires you to keep track of email IDs in the database, so you could check email from multiple computers and you would not get duplicate email.

To implement the advanced method, you need to:

• Make sure the Advanced functions are displayed in FileMaker Pro by enabling the “Show Advanced Functions in Calculation Dialog” option in the Configuration Dialog.
• Create an email account within the plug-in using the POP3it_ConfigureAccount function or the POP3it Configure Account script step. Alternatively, you can use the Account functions to programmatically create/edit accounts. If you are using the server plug-in, you must use the Account functions. See the Accounts Configuration page for more information.
• Connect to the Mail Server using POP3it_Adv_Connect.
• Go to the First Email on the mail server using POP3it_Adv_GoToMessage( “First” ).
• Start a Loop
• Get the current email’s UniqueID from the mail server using POP3it_Adv_GetUniqueID.
• Check if the UniqueID exists in your database. This could be done with a relationship or SQL.
• If the UniqueID does not exist, create a FileMaker record, and get the various email parts using functions such as POP3it_Adv_GetHeader, POP3it_Adv_GetBody, and etc.
• Check if any Attachments exist with POP3it_Adv_GetAttachmentCount.
• If Attachments exist, download them with POP3it_Adv_GetAttachment or POP3it_Adv_SaveAttachment.
• Go to the Next Email on the mail server using POP3it_Adv_GoToMessage( “Next” ).
• Check the result from POP3it_Adv_GoToMessage and if there are no more emails available, exit the loop
• Disconnect from the mail server using POP3it_Adv_Disconnect.

For an example of implementing the Advanced functions, see the Receive Email Advanced example database.