This is the first in a series of articles on using the Gmail API from FileMaker. We’ll provide free example files for each post and these examples will all use the native Insert From URL script step so there won’t be any plug-ins required.
In this article, we’re going to look at sending HTML emails. In future articles, I’ll examine sending large emails (35MB) with multiple attachments, resumable uploading, and managing threads. This approach provides a first-rate email experience that is not available using the native Send Mail script step. And, since the Insert From URL script step is supported natively across the whole FileMaker platform, the techniques shown here work on the Server, Go, FileMaker Cloud and WebDirect. This technique requires FileMaker 16 or higher since we’ll be using the advanced cURL options introduced in FileMaker 16.
Here’s an introduction. Step-by-step instructions and an unlocked example file follow:
Background and Choosing the Gmail API
I recently had the opportunity to build a comprehensive Gmail integration into a client’s system. The main reason the client wanted to go the Gmail route was to have seamless integration with their native Gmail experience; at first they weren’t that interested in threads or large attachments, but those features soon became important once they started emailing from within FileMaker.
Before we started, the client and I discussed which route we wanted to take, like using a plug-in or rolling our own. Fortunately, right about this time, dbservices published a great blog post and example file on integrating with the Gmail API. This article provided great techniques for authenticating to Google as well as creating an inbox in FileMaker that would import Gmails with their attachments. Basically, they had already done a lot of the work we needed. I implemented their authentication and inbox routine and then added the techniques I’m going to share here.
Please download the example file FM2Gmail for a working demo. This first version just covers the sending of HTML emails and we’ll be providing later versions of this file in future articles.
Getting Started / Authentication
Before we can send any emails, we’ll need to authenticate our app to Google. Our example file has adapted the authentication routine provided by dbservices where you’ll find more details on setting up a Google project for the OAuth values. Specify Web Application for your project so the redirect URI value is available. Once you’ve got your Client ID and Client Secret you can enter them into the fields on the OAuth settings page.
With your Client ID and Client Secret entered, you can click the “authenticate to gmail” link on the left. This opens a web viewer in a card window where you can log-into your Google account and authorize access to your Gmail data.
When you’ve successfully authenticated and authorized you’ll see your email address take the place of the “authenticate to gmail” link.
At this point, the example file has an authorization Refresh Token which we’ll use to automatically authenticate when the file opens in the future. So take some care with the file once it’s authorized as it will have access to your Gmail when opened. You can de-authorize the app access at any time by visiting “My Account” from your Google settings and then finding Apps with account access section. From there you can de-authorize the app.
Sending an HTML Email from FileMaker
Now that we’re authorized, the new email button appears, and we can compose and send something. I was going to use a card window for the compose layout, but I wanted to expose the formatting bar so went with a Floating window instead. (Exposing the formatting bar is an old FileMaker Hacks trick). Showing the formatting bar lets you easily add some styles to our text; those text styles will get transformed into styled HTML.]
I also added a simple emoji picker for fun. These are just button bars that are passing the emoji characters into the text. Since we’re just using the unicode characters, the emojis are a little spartan on Windows but work fine for a simple demo.
We can then send our Email and when we look at it in the recipient’s inbox we see that the styling has come across as an HTML email.
Under The Hood
To send an email via the Gmail API we first need to create the email form following the RFC822 standard. This multipart form may be familiar to many of you already and looks like the following:
Subject: Testing 123
Content-Type: multipart/mixed; boundary=01386EE1-2BC5-4670-8AC1-2C05A5CBA90D
Content-Type: multipart/alternative; boundary=5C6478EC-EDEA-43CF-AAC4-4B5AE4BC0649
Content-type: text/plain; charset=UTF-8
Content-type: text/html; charset=UTF-8
<span style="“font-weight: bold”;">Hello World</span>
In our sample file, the Script “Create RFC822 Form” is used to build the above. The RFC822 standard does call out using CRLF (carriage return + line feed) for the line breaks, but I had better luck just using the line feed or Char(10) in FileMaker terms. This allowed for leaving header values like CC blank and a more straightforward template.
Notice that there are two parts to this form that contains the message. The first is the text/plain section where we pass the plain text from our field. Since this is plain text, all of the formattings we applied is gone. Below, in the text/html section, we pass in the HTML representation of our message with any appropriate styling. Even though most modern email clients and browsers support reading HTML messages, it’s considered best practice to pass the plaintext message as well.
To generate the HTML in our sample file we’re just using FileMaker’s GetAsCSS() function. This actually works very well for a basic example and translates all of the formatting options except for any fonts applied. If you need a more robust HTML editor then something like FMEasyHTML from Tim Dietrich or Editor by Geist Interactive are worth checking out.
The Script “Send Email – Simple”
Once we have our form built, then we can POST it to the Gmail API using the Insert From URL script step. The example file does this in the script “Send Email – Simple”. Here’s what that script does:
Our target URL is:
This is the endpoint for our simple upload example and it supports an email up to 5MB. In the next article, we’ll be looking at a different URL that allows for up to 35MB with multiple attachments.
Now we just need to set a few cURL settings for our headers. (The exaple file writes the access token to a global variable when authentication is complete).
-H "Authorization: Bearer <<$$accessToken>>"
-H "Content-Type: message/rfc822"
And then specify our request body which is the rfc822 form we created above.
And also capture the result headers to a variable in case we need to examine them for errors.
That’s it!. This is all done in the script Send Email – Simple so you can step through there to see how it’s put together.
If there’s an error in the POST, an error code and message will be returned in the response body and headers. Otherwise, you’ll get a simple JSON response like this indicating the email has been sent.
Our script grabs the id and the thread id and writes those to the email record in FileMaker as we’ll be looking at using those in a future example.
Even though there is some extra effort involved in accessing the Gmail API, like authentication, understanding the syntax, and cURL requirements, the benefits provided by the API are well worth it. Having techniques that work across all aspects of the FileMaker platform to extend your app’s email functionality can provide massive value to your customers.
Additionally, as FileMaker developers, our understanding this kind of integration is going to be more and more expected as FileMaker continues to focus on integrating with other platforms. From my experience, every integration I do with a new API makes the next one easier. Even if you don’t have an immediate need for Gmail integration, running through this process and understanding how this API works with something familiar, like email, can only make you a better FileMaker developer.
Here’s the next article in this series: