SMTPit Pro

Next Generation Email plug-in


Coding Considerations

Getting Results

Every time you use an SMTPit Pro function, status text is returned back from the plug-in. This information can be very useful for letting you know if an error occurred. Consider the following:

Set Field[ db::result ; SMTPit_SetFrom( "myaccount@mydomain.com" )]

The above code will set the From email address to "myaccount@mydomain.com". If it was successful, the plug-in will return the following to the db::result field:

From Set to: myaccount@mydomain.com

However, if there was an error with the email address (for example, if the @ was missing), the plug-in will return something like the following to the db::result field:

ERROR: SetFrom: Invalid From: myaccountmydomain.com; From Cleared.

Error Checking

Including error checking in your scripting is vital to writing robust email scripts that will not break when something does not work correctly. Consider the following:

Set Variable[ $send ; SMTPit_Send]

The above code will send an email using any parameters (to, from, body, etc) previously defined. If it was successful, the plug-in will return the following to the $send variable:

Email Sent Successfully.

However, if an error occurred for any reason, the plug-in will return the error to the $send variable. For example:

ERROR: Send: Connect: SMTP Server Error: 5.7.8 Error: authentication failed

Notice the error begins with "ERROR:". Since all errors begin with this, you can write your scripts to look for this string. For example:

Set Variable[ $send ; SMTPit_Send]

If[ PatternCount( $send ; "ERROR:" ) > 0]

Take action here like:

Show Custom Dialog[$send]

Set Field[ db::result ; $send ]

Halt Script

End If

What your script does when an ERROR is encountered really just depends on what you want the script to do. In the above code, the script writes the error to the database using a Set Field script step, displays the error to the user via a Show Custom Dialog script step, and then Halts the script.

Writing errors to the database via Set Field is very important when using Set Variable script steps to call the plug-in. If an error occurs when using Set Variable, and you do not write the error to the database, the error message will be lost as soon as the script finishes.

For a list of errors the plug-in may return, please see the Error List page.

Curly Brackets

Curly brackets indicate that a parameter or parameters are optional. Take the SMTPit_Connect function for example:

SMTPit_Connect{( GetTranscript )}

This function can be called without any parameters because the parameter section is surrounded by curly brackets indicating that is it optional. Using the function in this manner looks like:

SMTPit_Connect

The above code would open a connection to your mail server. However, if you would like to get a Transcript of the interaction between SMTPit Pro and your mail server, you can specify True for the "GetTranscipt" parameter:

SMTPit_Connect( True )

In more complex functions, there may be multiple optional parameters. Note that if there are optional parameters before one that you need to use, you must include any parameters before it. Consider the SMTPit_StatusWindow function:

SMTPit_StatusWindow( Action {; Left {; Top {; WindowTitle }}} )

If you want to specify the "WindowTitle" parameter, you must also specify the two optional parameters before it. Following is an incorrect example and a correct example:

INCORRECT: SMTPit_StatusWindow( "Show" ; "Email Sending Status" )
CORRECT: SMTPit_StatusWindow( "Show" ; "" ; "" ; "Email Sending Status" )

FileMaker Version Considerations

When plug-ins were first introduced, the only place you really wanted to use a plug-in function was the Set Field script step. However, since FileMaker 4, many new advancements have taken place. Though the Set Field script step is still a very common place to use plug-in functions, there are now many places that can logically be used. For a list of a few of these places, see the next section titled "Places to use SMTPit Pro Functions".

It is important to keep in mind what versions of FileMaker will be in use when using SMTPit Pro and other plug-ins. For example, creating a variable using the Set Variable script step can be very convenient, however, that functionality only exists in FileMaker 8 and greater. If you or your users use FileMaker 7, then your script calls would fall on deaf ears if you used Set Variable script step. In addition, when using functions in a variable you will be less likely to see the results returned from the plug-in (such as error messages), because a variable cannot but put on a layout like a field.

Places to use SMTPit Pro Functions

You can use SMTPit Pro functions in any calculation engine dialog in FileMaker. Keep in mind that just because you can do something does not mean it is actually useful.

There are several places that fit very well depending on the situation:

  • Calculation field
  • Auto-Enter Calculated value
  • Validation by calculation
  • Set Field Script/Button step
  • Insert Calculated Result Script/Button step
  • Show Custom Dialog
  • Set Variable Script/Button Step
  • Custom Functions
  • and more...