Version 2.
A FileMaker Pro 4.x plug-in
Developed by
Comm-Unity Networking Systems
Emailing with FileMaker has
never been so easy and flexible!
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
Comm-Unity Networking Systems
Email:
[email protected] Web:
http://www.filemaker.comm-unity.net
Table Of contents
Introduction .................................................................. 2
Installation and Configuration ....................................... 4
Basics................................................................... 4
Header/Footer ...................................................... 5
Attachments ......................................................... 6
Email Headers...................................................... 7
After Send ............................................................ 8
About .................................................................... 9
How to Use FileMaker Plug-ins .................................. 10
Example Mailer Explained...........................................11
External Functions ..................................................... 12
Credits ........................................................................ 17
Contact Information .................................................... 17
Introduction
Introduction
Being able to send Email from within FileMaker Pro puts you in the drivers seat for complete
communication. SMTPit allows you to send Email with several custom made features that
just arent available in other products.
With SMTPit, mail merges are easy with our header and footer implementations! Imagine
having a custom introduction to each of your customers aimed directly at them, calling
them by name. From mailing lists to newsletters, SMTPit will make it simple, and give you
the ability to have custom footers for each Email
SMTPit also works well with Web Companion solutions. As your web visitors fill out web
forms you can immediately send them a personalized thank you note for visiting your site,
complete with details on products that your visitor specifically indicated they were interested
in.
Because SMTPit is so flexible, there are countless solutions. At this point, imagination is
the only limitation.
Features:
With SMTPit you will be able to send Email directly from FileMaker Pro using To, From,
CC, BCC, email headers, and attachments. Plus we have a few added features such as
a header and a footer that are added to the body of your email messages. For your
convenience, we have created a configuration box that allows you to set default settings of
each feature.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 4
Installation and Configuration:
To install the plug-in, first unzip the SMTPit zip file, and then double click the SMTPit_Installer application. This will
automatically place the SMTPit.fmx file into your System folder inside your FileMaker Pro 4.x folder. If you have a
previous version of SMTPit, the installer will overwrite it.
Once you have installed the plug-in as described above, you need to open FileMaker and set the default preferences
by going to Edit > Preferences > Application, click on the Plug-ins tab, and double click the SMTPit plug-in to begin
configuring it.
Basic Settings:
Once in the configuration box, click the "Basics" tab [see Fig. 1] and enter your smtp host in the Default SMTP Host
field, your email address in the Default From field, your name in the Default From Name field, and a default
subject in the Default Subject field.
SMTPit will refer to the default settings when you do not specifically set a value in your scripts. In other words, if you
do not specify a from email address in your SMTPit related script, the Default From address will be used.
Fig 1. The Basics
Configuration box.
The Basics tab is where
you put your default
SMTP host, From
address, from name, and
subject as shown here.
You can also adjust the
timeout settings if
needed.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 5
By default, SMTPit is set to a timeout of 30 seconds for your SMTP host to respond. You can adjust the setting to
fit your needs by entering a different value in the Timeout field.
Header & Footer Function Defaults:
SMTPit has the unique ability to add email headers and footers to the body of your messages. To enter a default
header or footer simply click on the Header/Footer tab [see Fig. 2] in the configuration box. Then simply click
in the desired field to enter a default header or footer. Like most SMTPit functions, you can replace the default
values in your current scripts with values from fields in your database. You can also use the related append
functions to add to both the default header and footer.
Because of this function, you can easily insert personal information into your email messages. You could have a
default header and footer shown, and use the SMTP-HeaderAppend function to add a personal message or
name to each email message. Another solution is to have a header or footer field in your database that is a
calculation. With this scenario you could dynamically insert product information from your database into each
email. Keep in mind that SMTPit also has a SMTP-BodyAppend function that can be integrated into such a
solution.
Fig 2. The Header/Footer
Configuration box.
The Header/Footer tab
allows you to enter a
default header and footer
which is placed in the
body of your email
message.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 6
Attachment Defaults:
SMTPit 2.0 introduces the ability to send attachments either using the default attachments set in the
configuration box [See Fig. 3] or via five new functions: SMTP-AttachAssign, SMTP-AttachAppend, SMTP-
DlgAttachAssign, SMTP-DlgAttachAppend, and SMTP-FileNameAcquire. To set a default attachment, one
that is always sent, click on the Add button under the attachments area of the Attach/E-Headers tab.
Once clicked, you will be presented with a dialog box which will allow you to navigate to your desired
attachment. Once you have found the file you want to attach, simply click the open button. To add additional
default attachments, simple repeat the process just described.
As mentioned above we have added five new functions to deal with attachments. The SMTP-AttachAssign
and the SMTP-AttachAppend functions require the complete path to be set. The SMTP-FileNameAcquire
aids in getting the correct path from your hard drive by giving you a dialog box to locate the desired file to
attach. The SMTP-DlgAttachAssign and the SMTP-DlgAttachAppend present you with a dialog box to choose
an attachment just like the default dialog mentioned above. For more information on these functions, refer
to the SMTPit External Functions Reference section of this documentation or take a look at the
SMTPit_Functions.fp3 file that came with the SMTPit 2.0 archive.
Fig 3. The Attach/
E-Headers Configuration
box.
The Attach/E-Headers
tab allows you to enter
default attachments and
email headers.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 7
Email Header Defaults:
SMTPit 2.0 also introduces the ability to insert extra email headers into your email messages. For
example, you can identify your company by creating an email header with the name Company with
the value being the name of your company. When the recipient gets your email message they will see
Company:Your Company Name in the header of their email. It is important that you do not have any
spaces in the Name of the header due to email header specifications, however, you can have spaces
in the value. You can also use email headers to track different email promotions or use POP3it to run
a script after downloading email from a pop3 email account to import an attached file.
To add a default email header simple click on the add button as shown below in Fig. 4, then type in
your desired header name in the name field with the desired value in the value field. You can also add
email headers dynamically by using the new SMTP-EmailHeaderAppend function which will append
new headers.
Fig 4. Add Email
Header...
This version of SMTPit
introduces the ability to
add email headers such
as Organization: Comm-
Unity Networking
Systems.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 8
After Send Defaults:
The After Send [see Fig. 5] settings will determine what action SMTPit will take once an email has been sent.
If you would like to receive a dialog box letting you know that your email message was sent, you will want to check
the Popup Email Sent Successfully Dialog option. This option is often helpful when debugging your scripts.
You also have the option to reset the following fields: To, From, Subject, CC, BCC, Body, Header, and Footer,
attachments, and email headers. Fields that are checked will be reset each time an email message is sent. Your
values will stay the same unless you have the related field checked in this box, use the SMTP-ClearAll function,
or use an assign function that will over write.
For example: If you have a default subject, and do not specify a new subject using SMTP-SubjectAssign or
SMTP-SubjectAppend, the default value will be used for your email message. If you assign a subject using
SMTP-SubjectAssign and also append your subject with SMTP-SubjectAppend and then send your email, the
subject will be reset if you have subject checked in the After Send box. However, if subject is not selected, you
can send another email message without specifying a subject at all and the previous values will be passed.
Fig 5. The After Send
Configuration box.
The After Send tab
determines what SMTPit
does after it sends each
message.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 9
The About Box:
The about box [see Fig. 4] simply reports which version of SMTPit that you are using. The about box can also be
brought up by using the SMTP-Version function. To make sure that you have the most resent version of SMTPit
please visit our website at http://www.filemaker.comm-unity.net
How to register your copy
With version 2.0 of SMTPit and in future versions, you can register your plug-in from the configuration box once
you have purchased it from our website or by ordering by phone. After you purchase SMTPit 2.0 you will be sent
a serial number to register your copy by using the Register button in the configuration box. We have also
decided to include a register function so that developers can easily register SMTPit with their bound solutions
once they have purchase a Developers license. For more information on purchasing SMTPit and other plug-ins
that we have developed, visit our website at http://www.filemaker.comm-unity.net and choose the Purchase link
from the tool bar.
Fig 6. The About box.
The About tab reports
which version of SMTPit
you are using.
To make sure that you
have the most current
version please visit our
website, which is listed
on the table of contents
page.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 10
How to Use FileMaker Plug-ins
FileMaker Inc. introduced a very simple plug-in architecture when they released FileMaker Pro 4.0. Meant to aid
in complex calculations, the plug-in architecture took off in ways that FileMaker had not expected. Though there
are now many different types of plug-ins, they all work the same basic way. By understanding the basics of plug-
in interaction you will be able to understand how many developers approach plug-in development.
To start with, plug-ins are used by creating calculations. You can use calculations in many places with FileMaker
including: a calculation field, the set field script, the paste result script step, as well as a text field that has a
calculated value. There are a couple of other ways to create calculations, but these are the major avenues that
are currently being used for plug-ins. The most commonly used avenue for plug-ins is the set field script step. It
is easy to use, plus, the plug-in can report its actions in the field that you are setting.
FileMakers External Plug-in architecture is as follows:
External (Function Name Prefix - Function Name, parameter)
For example if you take our Version function, which returns the version of SMTPit that you are using, it would look
like this:
External (SMTP-Version, parameter)
To actually use the function though, you will have to give it a parameter. Since the Version function does not
need any special information, you can just set it to 0 in order to use the function:
External (SMTP-Version, 0)
The parameter of the plug-in architecture is where you put the information for the related function. For example,
if you are setting your from address using the SMTP-FromAssign function, it would look like this:
Or if you were using a text field or a global field named From to hold your email address value, it would look like
this:
External (SMTP-FromAssign, From)
The difference between using a field to hold the value as compared to putting the real value into the calculation
is the quotation marks. This is because FileMaker will interpret anything not in quotes as a field in your database.
Though the calculation dialog box is limited in space, FileMaker has made it somewhat easier to deal with
functions by using their groupings of functions in the top right corner of the calculation dialog. To view all of the
plug-in functions currently installed, choose view by External Functions. Once chosen, you should see the
Web companion external functions, and if you have SMTPit installed you will see the SMTPit functions listed
there. Choosing to view by External Functions can greatly increase your script writing because the functions
that you are needing are right there at your finger tips.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 11
How the Mailer Example Solution works
This section of the documentation will show you step by step how the Mailer Example database works so
that you can understand how to better use SMTPit in your own solutions.
First of all there are twelve fields defined in the solution. You will not necessarily need all of the fields
mentioned in order to send email from your solution. Here are the field that I have created for this solution:
Field Name Field Type Formula / Entry Option
Date Date Auto-enter the: Creation Date
To Text
To Name Text
From Text
From Name Text
From Global (Text)
Header Calculation (Text) = Dear & To Name & ,
Body Global (Text)
Footer Global (Text)
Attachment Text
ReadMe Text
Note that not all fields are text. The From, Body, and Footer are global fields which will allow you to have the
same value for each record in your database. An alternative way to do this would be to use the default
settings in the Configuration box as discussed earlier in this documentation. Another type of field used is
the Header field which is a calculation. This is a very simple calculation that returns a greeting and the
name of the person that the current record is for. Note that the calculated result is set to be text.
Now that we have the fields in place, it is time to create a script to send an email. For this solution I have
named the mail script Send Mail. Here is what the script looks like:
Now lets go through the script step by step:
Script Step Script Parameters
Comment Data:
Clear Previous settings, and create new settings based on current record.
Set Field Result
Calculation
External("SMTP-ClearAll", 0) &
External("SMTP-ToAssign", To Name & " <" & To & ">") &
External("SMTP-FromAssign", From) &
External("SMTP-FromNameAssign", From Name) &
External("SMTP-SubjectAssign", Subject) &
External("SMTP-HeaderAssign", Header) &
External("SMTP-BodyAssign", Body) &
External("SMTP-FooterAssign", Footer)
Comment Data:
Send Message
Set Field Result
Calculation
External(SMTP-Send,0)
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 12
The first step is simply a comment field telling you what the next script step does.
The second script step first clears all previous values, and then sets the field Result to all of the
needed information to send the email. Note that the SMTP-ToAssign is a mixture of the two fields To
Name and To using the greater than and less than signs in quotes to create a complete email address
in the form of John Smith <[email protected]>. This format can be used for the To function as well as
the CC, BCC, and their related append functions. To create a free form name for the From address
you will need to use the SMTP-FromNameAssign function because of email header standards.
Everything else in this script step is straight forward, simply setting values from fields to their related functions.
You could also add other things to this calculation, such as a field that holds the path to an attachment
that you want to send using the SMTP-AttachAssign function. The field could be a calculation so that
you can send different attachments based on the current record, or you could ad a new field to your
database for a file name, and then set the SMTP-AttachAssign function to a predefined path plus the
name of your file. Such a calculation might look like this:
External (SMTP-AttachAssign, C:\attachments\ & Filename)
This scenario would ideally let you send a different attachment to each person if needed. Keep in
mind that you can also set a default attachment in the SMTPit configuration box mentioned earlier in
this documentation. Also keep in mind that you can use the SMTP-AttachAppend function to add
attachments, so realistically, you could have a default attachment that you send, plus an attachment
specifically for each person.
The third script step is another comment the telling you that the next script step is the step that sends
the message.
The fourth script step sets the field Result to SMTP-Send, and the SMTPit plug-in will report the
result of the action in the result filed. Keep a close eye on this field when you are trying to debug your
scripts because it will tell you what is going wrong if the email is not sent. You could actually combine
steps 2 and 4 into one calculation, but I have separated them here in order to make the Result field
easier to read.
The Send All Script
The send all script is very simple. It first finds all of the records in your database, and goes to the first
record. At that point the script enters a loop, runs the Send Mail scrip that I describe above, goes to
the next record and runs the Send Mail script again until it gets to the last record and then it exits the
loop and finishes the script. If you want to send email to a found set I would suggest taking out the
Find All script step, and then running the Send Mail script. This will still run the loop starting with the
first record and continuing until the last record of your found set.
The Attach File Script
This script simply calls the SMTP-DlgAttachAssign function that allows you to locate a file on your
hard drive to attach to the current email. Note that the send mail script uses the SMTP-ClearAll
function at the beginning of the script, so that will reset the attachments each time. If you want to
include specific attachments to specific records I would suggest using the example above which will
integrate the SMTP-AttachAssign function directly into the Send Mail script.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 13
SMTPit External Functions Reference:
SMTPit has three different types of functions that make Emailing with FileMaker more flexible and easier to use.
First, there are functions that assign values. Second, there are functions that append values. Third, there are
functions that effect all Email fields such as SMTP-AssignAll, SMTP-ClearAll, and SMTP-Send. Following is a
list of all available functions and a complete description of each. Note: there are several functions that can have
default values that are set in the Plug-in Configuration box. See the Installation and Configuration section to get
a complete understanding of how the configuration box works. Note that functions with an * are new with
version 2.0.
SMTP-Version
Opens the about box for SMTPit. Will also allow you to configure SMTPit. The parameter should be set
to or to 0 (zero).
SMTP-AssignAll
Assign all Email header fields at one time in the form of:
External(SMTP-AssignAll,Host=smtp.your.com|[email protected]|
[email protected]|[email protected]|
BCC:[email protected]|subject=yoursubject)
The SMTP-BodyAssign, SMTP-AssignHeader, SMTP-AssignFooter, SMTP-AttachAssign,
SMTP-DlgAttachAssign, SMTP-EmailHeaderAppend and related append functions must be set separately.
The SMTP-AssignAll function is only for Host, To, From, CC, BCC, and Subject. Note that the Email fields
can be in any order, but must be separated by the | (Pipe) character.
SMTP-ToAssign
Use the SMTP-ToAssign function to assign the To Email header. Once assigned you can add other Email
addresses by using the SMTP-ToAppend function. Note: if you use the SMTP-ToAssign function twice,
the second one overwrites the first.
SMTP-ToAppend
The SMTP-ToAppend function will add Email addresses to the To Email header. If no Email address has
been set by SMTP-ToAssign, SMTP-ToAppend will assign your current value to the To field. SMTP-
ToAppend can be set multiple times, whereas SMTP-ToAssign can only be set once without overwriting
previous settings.
SMTP-FromAssign
Use the SMTP-FromAssign function to assign the From email header. Note: if you use the SMTP-
FromAssign function twice, the second one overwrites the first.
SMTP-FromNameAssign
The SMTP-FromAssign is used to assign the from name when sending email. This is the name that will
show up next to your email address when you send mail with SMTPit. You can also set a default from
name in the configuration box.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 14
SMTP-SubjectAssign
Use the SMTP-SubjectAssign function to assign the From email header. Note: if you use the
SMTP-SubjectAssign function twice, the second one overwrites the first.
SMTP-SubjectAppend
The SMTP-SubjectAppend function will add to the Subject email header assigned by SMTP-SubjectAssign.
If no subject has been set by SMTP-SubjectAssign, SMTP-SubjectAppend will assign your current value
to the Subject field. SMTP-SubjectAppend can be set multiple times, whereas SMTP-SubjectAssign can
only be set once without overwriting previous assignments.
SMTP-CCAssign
Use the SMTP-CCAssign function to assign the CC (Carbon Copy) email header. Note: if you use the
SMTP-CCAssign function twice, the second one overwrites the first.
SMTP-CCAppend
The SMTP-CCAppend function will add to the CC email header assigned by SMTP-CCAssign. If no CC
has been assigned by SMTP-CCAssign, SMTP-CCAppend will assign your current value to the CC field.
SMTP-CCAppend can be set multiple times, whereas SMTP-CCAssign can only be set once without
overwriting previous assignments.
SMTP-BCCAssign
Use the SMTP-BCCAssign function to assign the BCC email header. Note: if you use the SMTP-BCCAssign
function twice, the second one overwrites the first.
SMTP-BCCAppend
The SMTP-BCCAppend function will add to the BCC email header assigned by SMTP-BCCAssign. If no
BCC has been assigned by SMTP-BCCAssign, SMTP-BCCAppend will assign your current value to the
BCC field. SMTP-BCCAppend can be set multiple times, whereas SMTP-BCCAssign can only be set
once without overwriting previous assignments.
SMTP-BodyAssign
Use the SMTP-BodyAssign function to assign the Body. Note: if you use the SMTP-BodyAssign function
twice, the second one overwrites the first.
SMTP-BodyAppend
The SMTP-BodyAppend function will add to the Body email header assigned by SMTP-BodyAssign. If no
Body has been assigned by SMTP-BodyAssign, SMTP-BodyAppend will assign your current value to the
Body. SMTP-BodyAppend can be set multiple times, whereas SMTP-BodyAssign can only be set once
without overwriting previous assignments.
SMTP-Send
Spools the email message and sends it during idle time. The parameter should be set to or 0 (zero).
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 15
SMTP-SendWait
Sends the email message. This function waits to confirm that the message has been sent to the SMTP
server before continuing the script. You can also have SMTPit confirm that a message has been sent
showing you an alert dialog. This setting can be found in the Plug-in Configuration box. Like the SMTP-
Send function, the parameter should be set to or 0 (zero).
SMTP-ClearAll
The SMTP-ClearAll function clears all fields so that the next email can start with a clean slate. You can
also set SMTPit to automatically clear/not clear specific fields in the Plug-in Configuration box.
SMTP-HostAssign
The SMTP-HostAssign is key in the emailing process. You can assign the host each time, or setup a
default host in the Plug-in Configuration box.
SMTP-HeaderAssign
This is a unique function that will allow you to have a body header in your email message. Possible
uses are email letterheads or personalized email messages for mass emailing. SMTPit also allows you to
set a default header in the Plug-in Configuration box. If you assign a header using SMTP-HeaderAssign,
the default header will be ignored.
SMTP-HeaderAppend
The SMTP-HeaderAppend will append text to the current body header, whether it is the default header or
a header assigned by SMTP-HeaderAssign.
SMTP-FooterAssign
Another unique function in SMTPit is the SMTP-FooterAssign which will allow you to have a body footer.
Possible uses include a email signature, a public key, an email advertisement, quotes, or a passage
telling how to unsubscribe from your list. You can set a default header in the Plug-in Configuration box. If
you assign a footer using SMTP-FooterAssign, the default footer will be ignored.
SMTP-FooterAppend
Like the SMTP-HeaderAppend, the SMTP-FooterAppend appends text to the current body footer, whether
it is the default footer or a footer assigned by SMTP-FooterAssign.
SMTP-AttachAssign*
The SMTP-AttachAssign function allows you to set a path to a file on your hard drive or network that will
be attached to the current email being sent. Note that if you use the SMTP-AttachAssign function multiple
times, you will overwrite the previous setting each time.
SMTP-DlgAttachAssign*
This function lets you choose a file from your hard drive to be attached to your current email being sent. It
uses a standard dialog box that allows you to navigate to your desired file.
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
SMTPit Page 16
SMTP-AttachAppend*
The SMTP-AttachAppend function works exactly like the SMTP-AttachAssign function except that it adds
attachments to your current attachments list.
SMTP-DlgAttachAppend*
The SMTP-DlgAttachAppend function works exactly like the SMTP-DlgAttachAssign function except that
it adds attachments to your current attachments list.
SMTP-EmailHeaderAppend*
The SMTP-EmailHeaderAppend adds email headers to your email messages. Note that there should be
no spaces in the name section of the header, however the value can have spaces. This function takes the
shape of: External (SMTP-EmailHeaderAppend, name=value). In other words, the first value is the
name and the second value is the value of name, and they are separated by the equal sign. Note that you
can also set default email headers in the SMTPit configuration box.
SMTP-FileNameAcquire*
This function allows you to use a dialog box to navigate to a desired file. The field that you set the
calculation to is set to the path to the file that you choose.
SMTP-Register*
This function allows you to register your copy of SMTPit via a function rather than using the configuration
box. It is mostly meant for developers so that they can register plug-ins for bound solutions. This function
takes the form of: External(SMTP-Register,First Name|Last name|Serial Number). In other words, the
parameter consists of your first name, last name, and serial number all separated by the pipe character.
(| is created by shift backslash)
Credits:
Programming by Jake Traynham
Concept, web design, and documentation by Jesse Traynham
Contact Information:
Email: [email protected]
Web: http://www.filemaker.comm-unity.net
Phone: 817-560-4226
You can write us at:
Comm-Unity Networking Systems
8652 Hwy 80 West
Fort Worth, Texas 76116
SMTPit 1999 Comm-Unity Networking Systems - all rights reserved
