Introduction
With SMTPit Pro, you can use Merge Fields in your email messages. A merge field is a tag representing a field which will get replaced with the field’s contents when the message is sent.
For example, if you have a field called “Name”, you can represent this field in your email message as “<<Name>>”. If your “Name” field happens to be in a table called “Contacts”, then you would use “<<Contacts::Name>>” as your merge field tag. If the value in the “Name” field is “Joe Cool”, then SMTPit Pro will replace “<<Name>>” with the text “Joe Cool” when the email is sent. Merge fields can be used in the subject, header, body, and footer of your email messages. SMTPit Pro will automatically replace merge fields with their corresponding field values when sending a message. If the SMTPit Pro cannot find the field you are trying to reference, it will place a question mark “?” in place of the merge field.
Download Example File
Settings
- 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.
MergeText Function
To help you preview what an email message might look like after it is merged, we have included the “SMTPit_MergeText” function. Remember, this function is only for previewing, there is no need to include it in your send mail calculations. For more information on this function, be sure to check out the “Function Reference” or click on the function name in bold.
There are actually two body fields above. The first field is called “Body” and is a regular text field. The second is a calculation field called “Body Merge Preview”. This second field uses the SMTPit_MergeText as follows:
SMTPit_MergeText( Body )In other words, it takes the text in the “Body” field and replaces any merge fields with their corresponding field values. The “Body Merge Preview” field is on top of the “Body” field, and is set so that the user cannot enter the field. The end effect is that you can click and edit the “Body” field, but the “Body Merge Preview” field is displayed once you have exited the “Body” field.
Send Script
This “Send” script is virtually identical to the “Send (Simple)” script that is found in the “Send Text Email” example. Please view that example for a thorough explanation of how the script works.
View Results
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.How to recreate in your solution
Following are the exact steps to recreate the body merge preview:
Create Fields...
- Go to the "File" menu down to "Define", and then choose "Database..."
- Create a new text field named "Body".
- Create a new calculation field named "Body Merge Preview".
- While in the calculation for the "Body Merge Preview" field, change the "View" menu in the upper right hand corner to "External Functions" and locate the "SMTPit_MergeText" function. Once found, double click on it to insert it into the calculation.
- Replace the "Text" parameter with the "Body" field by double clicking on the "Body" field in the field names on the top left of the dialog. Your final result should be:
SMTPit_MergeText( Body ) - Click "OK" to get out of the calculation dialog.
- Click "Done" to dismiss the "Define Fields" dialog.
Set up fields on layout...
- Enter layout mode by going to the "View" menu and choosing "Layout Mode".
- Drag a copy of the "Body" and "Body Merge Preview" fields onto your layout.
- Resize both fields so that you can easily type in an email.
- Select the "Body Merge Preview" field go to the "Format" menu and choose "Field Behavior...". Uncheck "In Browse Mode" so that the field cannot be entered while in browse mode. Click "OK" do dismiss the "Field Behavior" dialog.
- Test the fields by typing something in the Body field. Be sure to use at least one merge field referencing a different field.
- Move the "Body Merge Preview" field on top of the "Body" field, you may need to use the "Arrange" menu to bring the "Body Merge Preview" field in front of the "Body" field. You may also want to use the "Arrange" menu to set the alignment of the fields.
